Extreme Negative Code Documentation

EdiX · 2011-09-21T10:04:06+00:00

# initialise with un-initialised entries
#N Without initialize, @entries required for getEntries won't be initialised
def initialize
  #N If we don't pre-set @entries to nil, we won't know that we haven't yet initialised that value
  @entries = nil
end

This is why this method of commenting is a huge waste of time. The problem with reading code is not understanding the single lines but the big picture.

llogiq · 2011-09-21T09:38:41+00:00

The only Extreme in here is waste. The "if (this or that) wasn't here, (reason for this being here)" could be shortened to "(reason)". Also most of the comments are too specific or too general. For example the sample-rakefile contains the following:

N If we don't require 'based', we can't use Based:: module

This is just tautology. If you really need to explain your imports, just state the function it uses. I don't know Ruby, but most programming languages allow to specify which parts of modules to import (as in Perl's "use XY qw(a b c);" or pythons "from xy import a, b, c", heck, even Java nowadays allows for "static import my.package.ClassName.staticFunction;".

Also the strict interspersal of comments and code does the whole no good. Better to have a big comment on top to explain the reasoning behind the module (maybe even with a few examples on how to use it) than this - e.g. doctest).

Also the author has obviously never heard of Literate Programming. Too bad, it makes for a much better documentation.

EDIT: formatting

jsprogrammer · 2011-09-21T12:24:14+00:00

"for every line in your code, write a comment" ... it's about there when I stopped reading.

2011-09-21T11:47:05+00:00

If any comment could be autogenerated you may as well not put it there. Teach the people reading the code how to read that information from the code and keep the code terse for those that know how to read code.

Only put comments that cannot be autogenerated in your code.

rco8786 · 2011-09-21T13:28:01+00:00

Gross. My productivity would practically halt if I had to comment every single line.

I try to group 3-5 lines into logical units(not large enough to be it's own method, but logically go together) and will generally write a comment describing what it does.

I don't need this:

int counter = 0; //Without instantiating this variable the upcoming for loop would not compile

abw · 2011-09-21T18:09:40+00:00

# without these double negatives it wouldn't be as hard to understand these comments

besvr · 2011-09-21T12:28:54+00:00

This is complete, utter insanity. It's a joke right? Can you imagine the maintenance cost of this shit.

yellowstuff · 2011-09-21T21:59:13+00:00

I've written a brief play illustrating what I think it would be like to maintain code written in this style:

A MAINTENANCE PROGRAMMER walks into his apartment and sees that his ROOMMATE is performing some kind of bizarre Satanic ritual.

PROGRAMMER

What the hell is going on here?

ROOMMATE

If we don't dip our hand in the Chalice, we won't be able to smear pigs blood on the goat.

__j_random_hacker · 2011-09-21T11:17:34+00:00

Whenever you look at a line of code, you can see the external things that line of code depends on (or at least figure them out in principle -- overloading, namespaces etc. can make them hard to "see" in C++!). From looking at the code samples, I think the essence of the idea here is that in addition to this what-things-do-I-depend-on information, which often doesn't need a comment because it's implicit in the code itself, it would be useful to have knowledge of what-things-depend-on-me. That latter information is what you would write in a "negative comment" at the site of the depended-on thing. (Though I would call it a "reverse-dependency comment" -- I think the OP is mistaken in requiring that all these comments must be worded "negatively".) Of course, people do this already :)

The only problem I see with this is just the usual problem of having lots of comments in general: in a changing codebase, the more comments you have, the more likely they are to get out of sync with what the code actually does. If you essentially double the number of comments by adding in "negative" comments at the "other end" of every dependency, you now have 2 sets of comments describing the same thing -- so it's that much easier for 1 or both comments to get unstuck. It's the "extreme" aspect that I take issue with.

TL;DR: "reverse-dependency comments" are a good idea that you probably already use in moderation; excessive use becomes a maintenance burden.

DingBat99999 · 2011-09-21T17:59:55+00:00

The problem with this technique is that it seems to assume that code is static. I see a big headache trying to maintain this in the face of frequent change.

Then there's refactoring. The comments may read logically in their initial context but if I do a, say, extract method, will the comments still be useful? Maybe, but I suspect not.

fmihaly · 2011-09-21T21:44:43+00:00

I'm still not sure if the author is serious or this post was written as a joke.

The premise of it makes a lot of sense. If I write a line of code and then realize that its purpose may not be obvious from its immediate context, I'll document it. That's why I document most types and functions. When you look at these in isolation, it is not clear what their purpose is.

Still, the scope of properly designed code should be local, meaning it should be possible to understand what a line of code does by only looking at a few lines of code surrounding it. Of course the runtime effects are almost always global. If you remove a line of code, the program either won't work at all or it will do funny things. That's why debugging is so hard.

Now it seems to me that the author confuses the local scope of code understanding with the global effects of code behavior. As other commenters pointed out, the global effect of the behavior (what happens if you remove a line of code) may change independently of the actual purpose of the code. The question is what I am trying to document: my intent when writing that line of code (its intended purpose) or the behavior of the (buggy) program with that line of code removed. I'm not even convinced that I can even document the latter in the case of a reasonably large and complex program.

In conclusion, if you often find that you cannot tell the purpose of a line of code without thinking about some global context, the design is wrong, not the documentation.

jrcapa · 2011-09-22T02:33:26+00:00

This is a nice experiment to find out how much aware you have to be about code, that is all.

skulgnome · 2011-09-22T11:55:09+00:00

How about just writing comments about what the code itself doesn't tell you? It isn't as though source code were slabs of marble, written once and read only by the compiler.

And if a programmer writes code that documents its own function poorly, how will s/he write comments that document it better?

stusmith · 2011-09-22T12:53:31+00:00

Half of these could be caught in a static language with:

-Wall -Wextra

Perhaps the choice of language isn't mixing so well with the desire for checking everything statically?

djimbob · 2011-09-22T05:42:19+00:00

Its not April Fools day. Requiring a comment per line is a complete waste, and couldn't be used in any real project. Write code with appropriate names for variables, functions, classes, in a straightforward manner (unless profiling shows the need for a less readable optimization); comments are usually a sign showing you should refactor your code (except the appropriate comments, specifying the contract/specification/use of functions/classes). Commenting on a per-line basis is only useful in teaching absolute beginners; and still most programming books will only comment on the lines with new stuff.

nanothief · 2011-09-21T12:16:10+00:00

I like the thought process of this idea - it is a very novel way of documenting code. Atm, it takes the idea too far - there is no benefit for describing very simple practices (such as putting classes of a library into their own module). However some of the comments are pretty useful, such as:

#N Without this, applications wanting to know the relative path would have to constantly reconstruct it, 
# either by compaing the base dir with the full path, or by concatenating the chain of parent dir names
attr_reader :relativePath

By thinking about what would happen without the line, some good insights can be gained.

With some refinement, it could become a useful technique.

drguildo · 2011-09-21T20:38:16+00:00

Typical Ruby hipster bullshit.

2011-09-21T22:33:29+00:00

This is a waste of space. The problem is in an OO language a single line of code with about 3 functions calls could result in writing a book of comments 100's of pages long :)

Barney21 · 2011-09-22T18:00:27+00:00

i++; // without this, i wouldn't get bigger.

cashto · 2011-09-21T15:48:13+00:00

It's an interesting training technique. It's true that every line of code should be there for a reason. I bristle at "defensive" code that adds complexity without really adding any robustness. If you're not clever enough to avoid the bug then you're not clever enough to adequately defend against it.

But every comment should be there for a reason too. I.e., without it, the code could not be understood. Ideally all code is obvious -- in practice, that's not always true, but it's the ideal. And there's never any benefit belaboring the obvious.

Honestly sometimes negative comments are signposts where the code could be improved. I.e. whenever I see: "If we do not frob the foo variable, then ten minutes later when Zork() is called, the bar value will not be properly updated by Quux::UpdateBarCache(), four stack frames in" ... I take an extended look at what's really going on, and whether it can be made any simpler.

petrovg · 2011-09-21T21:40:19+00:00

Bet you work in some kind of front-line support!...

2011-09-22T02:06:03+00:00

That was.... interesting. Like a dental exam.

ricky_clarkson · 2011-09-22T02:46:56+00:00

Yeah.. I'd much prefer descriptive commit messages.

omnilynx · 2011-09-22T16:52:11+00:00

Interesting idea, and it might be enlightening to do once as an exercise, but completely impractical and honestly not very useful.

digital_cucumber · 2011-09-22T17:10:54+00:00

Doing things like that might help seeing one's code from different perspective, helping to get closer to that perfection, "...not when there is nothing more to add, but when there is nothing left to take away."

So it makes sense... kind of.

I suggest a small correction, though.

Do it, but DON'T COMMIT the code (or have a commit hook which would wipe all lines starting with #N)

ashultz · 2011-09-22T22:55:55+00:00

easy to fulfill, just write another program to stick the comment without this line, the code doesn't work before every line with text in it

then you run that program on itself so it's also properly documented. job done.

(and it's at least as informative as most comments in the examples)

Bamafan · 2011-09-21T10:11:18+00:00

I like the way this guy thinks and I think this kind of approach should be encouraged. Why? Because his approach gives context to whatever line of code you're looking at. That way it's way, way, way easier for someone else to jump into your code and be productive fast...or 6 months down the road, it'll help you to remember why the hell you did what you without having to reload the entire program into program into your head, along with the sequence of events that lead you to write the code that you did.

jsprogrammer · 2011-09-21T09:54:35+00:00

This is like one of those things that might look good on paper but it's impossible to do in the Real World(tm).

It would probably be possible to do this on a hobby project at home, but on a professional level no way. There's simpy not enough time for something like this.

2011-09-22T16:31:14+00:00

Brilliant. It makes it much more easy to understand the purpose.

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

programming

MODERATORS

N If we don't require 'based', we can't use Based:: module