Commenting code

[jack]

I think my brain is hardwired to solve problems in the most elegant way. This has good consequences (I got a good degree from Cambridge, am paid £n0k/yr to program, and can beat Tony at noughts and crosses generalisations) and bad consequences (I don't like asking for directions or other help, I find it hard to get on well with people, etc).

When I was young, it used to almost be a point of pride that I didn't comment my code. Now I do so quite well, or so I believe. But I think both stem from the same underlying trait. When I was young, I saw the problem as "Write this program." Now, the problem has evolved into "Write this program so it works, and solves a specific problem, and in the future update it with the least possible effort."

Comments

[mr-ricarno.livejournal.com]

I think my brain is hardwired to solve problems in the most elegant way.

Aha! So you're the one who stole Occam's Razor!

[aldabra]

I used to think commenting code was a waste of time.

Until my first assignment in my previous job was to learn C and take over maintaining 100,000 lines of home-grown system, whose writer had left, and whose comments were restricted to one-liners saying things like "Bet you can't see why I've done it like this!" and variables were called things like isnull and were true if it wasn't and false if it was.

Now I think the standard should be that *someone else* can update it in the future with the least possible effort, and you shouldn't necessarily assume that they've used the language before...

[cartesiandaemon.livejournal.com]

Yeah. If you optimistically assume coding is 99% of the time -- which it might be for a short purely technical personal project -- coding adds a lot. But nowadays almost all the time is working out what you should make things do, writing it is easy, so comments become *part* of the working out time.

"Bet you can't see why I've done it like this!"

ROFL.

Now I think the standard should be that *someone else* can update it in the future with the least possible effort

That's about right. As a matter of fact I tend to think of "myself, with no memory of this code whatsoever" which is often close to the truth.

be that *someone else* can update it in the future

[cartesiandaemon.livejournal.com]

This standard also avoids /* Add one to x, wraps at 2^n */ comments because it's obviously not useful :)

[feanelwa.livejournal.com]

*applauds* hear hear.

Why yes I have been fixing other people's code for the last two days, why do you ask?

[beckyc.livejournal.com]

Quite frequently, asking for directions is both the most simple and elegant way to do things.

Other times, of course, it's shameful and means losing face. Knowing which is which quickly is important.

[mair_in_grenderich]

but is it the most fun? :-)

[cartesiandaemon.livejournal.com]

ROFL. Exactly. It's easy to get stuck on being determined to figure it out for yourself when the real goal should be to get where you're going. If you're enjoying walking in nice weather, that's good, but if you're in a hurry that's bad.

[ewx.livejournal.com]

You might have seen this already but it's a nice story about a famous comment

[cartesiandaemon.livejournal.com]

LOL. I'd seen mentions of the comments, but never didn't remember the explanation. Thanks.

[uisgebeatha.livejournal.com]

When I was young, it used to almost be a point of pride that I didn't comment my code.

As a young geeklet, it has to be said that I'm the opposite; I comment my code all the time, but that's because I'm a forgetful pixie. You might say I comment excessively, but I like to explain things well, so it can't be a bad thing. And when I move onto languages that are less fluffy than Java, commenting might be a good thing indeed!

Of course, you could always follow the silly rules of commenting. My personal preference is /* magic happens */ :P

[cartesiandaemon.livejournal.com]

LOL. I was forgetful too, I just didn't realise until later in life :) I don't think I've ever seen real code commented too much.

/* magic happens */ :P

ROFL. Of course, sometimes that's the right comment -- if the author doesn't understand the code then that is a correct comment and the problem is in the code not the commenting :)

[douglas-reay.livejournal.com]

What priority would you give the following in your comments?

What. How. Why. Who. When.

What - the contract a function or object agrees to fulfill (arguments, checking, errors thrown, arguments returned, side effects, memory or resource usage - eg who frees the memory used by stuff passed and returned)

How - how does it implement this contract (Eg "Implements Kruskal's Algorithm")

Why - why does it do what it does? The reasons behind your design and implementation decisions ("Optimised for memory usage not speed because concurrent with process Foo that will always take 10 times as long")

Who & When - revision history & responsibility


Personally I'd like to see What, Who and When comments all handled automatically. I'd like the "How" to be as obvious as possible from the code itself. It is the "Why" that you often can't work out from one bit in isolation - you need to know the whole fragging system.


Douglas

[cartesiandaemon.livejournal.com]

Ack. I hadn't thought of it like that. Who and when have some info stored automatically, but doing more is slightly awkward, what decides what unit 'who' should apply to? If A writes a function it should never be big enough that B can need to edit a line of it without understanding the whole function, but that does happen.

If you know what, you might at least be able to work out how, but without what you have to understand the rest of the system. Why is great, but generally out of date.

If you have good what/why, who/when are less vital, but always necessary in working out what/why.