Document the Why

Re:Document the Why by Ensorceled on Wednesday March 06, 2013 @10:31AM (#5331606)

I've been putting essentially this same advice in coding guidelines for about 20 years now:

    Comments explain why you are doing something, your code
    should be written in a style that automatically shows the
    who, what and how.

[ Parent | on HN ]

Re:Document the Why by ctdonath on Wednesday March 06, 2013 @12:11PM (#5332231)

"When" too. Nice to know whether the weirdness was added last week or last decade. I've left old obtuse comments in place just as proof that the function, as written, was there for the last 14 years (which sometimes explained a lot).

[ Parent | on HN ]

Re:Document the Why by Ensorceled on Wednesday March 06, 2013 @06:39PM (#5334835)

I don't find when useful, except in post mortem situations. The code is the code. Trying to capture history leads to things like old code being commented out to preserve the context. Use a good code repository instead.

[ Parent | on HN ]

Re:Document the Why by mercurial on Wednesday March 06, 2013 @02:19PM (#5333192)

git annotate?

[ Parent | on HN ]

Re:Document the Why by ctdonath on Wednesday March 06, 2013 @03:08PM (#5333482)

I'm talking code that has out-lived several "yeah we'll use this forever" version control systems. If the comment isn't in the code it will get lost.

[ Parent | on HN ]

Re:Document the Why by ZoFreX on Wednesday March 06, 2013 @04:30PM (#5334106)

FWIW you can actually migrate between most major VCS systems without losing your history.

[ Parent | on HN ]

Re:Document the Why by Someone on Wednesday March 06, 2013 @04:51PM (#5334249)

Yes, but it is neigh impossible to migrate from say Python to C, a copy-paste into an entirely different project, and from there via Java to C# and keep history. That may be a stretch, but even one such step will almost certainly lose history.

[ Parent | on HN ]

Re:Document the Why by mercurial on Wednesday March 06, 2013 @05:23PM (#5334445)

It also depends on what kind of stuff you've done with your VCS. "Creative" SVN layouts may be difficult to merge.

[ Parent | on HN ]

Re:Document the Why by ctdonath on Wednesday March 06, 2013 @08:29PM (#5335349)

That's assuming somebody remembers where it was.

[ Parent | on HN ]

Re:Document the Why by stcredzero on Wednesday March 06, 2013 @10:36AM (#5331635)

What does "who" mean in this context?

[ Parent | on HN ]

Re:Document the Why by EvilTerran on Wednesday March 06, 2013 @10:52AM (#5331736)

I'd take that to mean "who wrote the code"; so it's less of a coding style guideline, more coding strategy: "use version control with per-person accounts, so you can tell down the line who made a change".

[ Parent | on HN ]

Re:Document the Why by stcredzero on Wednesday March 06, 2013 @12:22PM (#5332299)

> I'd take that to mean "who wrote the code"

Which would make sense, except that it's the code itself said to indicate this. Or, does he mean for that to be documented in the RCS?

[ Parent | on HN ]

Re:Document the Why by Ensorceled on Wednesday March 06, 2013 @06:48PM (#5334866)

The developer.

I ended up firing a guy because he would not stop littering the code with crap like:

    // 2 lines added by I. Dee Ott Feb 12, 2005
    // increment i
    i++;
    // 1 line removed by I. Dee Ott, Feb 12, 2005
    // i = i + 1;

But also the actor or user role.

    // this function can only be run by admin

Is only true if enforced in some way.

[ Parent | on HN ]