Do you like documentation in code, and if so, how/when?

[sourmìlk]

I compulsively do not comment unless I know that other people will be looking at the code. I like the way non-commented code looks, and I try to make my names descriptive, so I feel that it's almost always redundant, and when it's not, it looks ugly and out of place. These are not very good reasons, they're mostly just preferences. My multi-thousand (so far) line game engine has no comments in it.

[WarDaft]

If you're looking to improve your commenting I'd recommend asking a classmate to read your code and see if they understand how your program works.

I have to second this. I only just recently discovered just how incredibly difficult it can be to read someone else's code, even when you are working side by side, in the same room but different computers, on exactly the same problem, with the exact same level of instruction on the language.

It was like trying to read an alien language.


I comment a lot more liberally now, even if it's not required for assignments, or even seemingly necessary due to (at least me thinking that my project is) well structured code. I feel so sorry for the TAs for that course.

[EvanED]

I compulsively do not comment unless I know that other people will be looking at the code.

My problem with this thinking, even if it's completely correct in the literal sense, is that "me in 6 months" is almost guaranteed to be another person.

One of my proudest moments from coding occurred when the following happened. I got some code from some other people. It was kind of complicated, but necessarily so, because we were trying to use an API that did what we wanted, but getting the answer out took some work.¹ Figuring all this out the first time took probably 30 minutes or an hour of me and a colleague looking at the code. I wrote up a description of this process in a nice long comment.

About 8 months later, I came back to that same code so I could change something. And while I have no doubt that I'd have had a much simpler time figuring out what it did the second time around, that comment I wrote made it completely trivial, as there was nothing left to figure out.

Anyway, I prefer self-documenting code when they do the same thing. Like I'd never do int x; // number of moons of Jupiter or something like that. But self-documenting code only goes so far.

¹ To make this a bit more concrete, it's about accurate to say that we were building up a string, but what we had was a callback function that, when called, we'd append another letter to the string. But some letters were computed based on the result of two successive calls. So we had to keep around some auxiliary information from the first call to use in the second, then detect whether we were in a "normal" case, the first call of one of these special cases, or the second call of one of these special cases. (I also kept around some additional state to sanity check that the callback was giving us things in the right order.)

[Sagekilla]

I compulsively do not comment unless I know that other people will be looking at the code.

My problem with this thinking, even if it's completely correct in the literal sense, is that "me in 6 months" is almost guaranteed to be another person.

One of my proudest moments from coding occurred when the following happened. I got some code from some other people. It was kind of complicated, but necessarily so, because we were trying to use an API that did what we wanted, but getting the answer out took some work.¹ Figuring all this out the first time took probably 30 minutes or an hour of me and a colleague looking at the code. I wrote up a description of this process in a nice long comment.

About 8 months later, I came back to that same code so I could change something. And while I have no doubt that I'd have had a much simpler time figuring out what it did the second time around, that comment I wrote made it completely trivial, as there was nothing left to figure out.

Anyway, I prefer self-documenting code when they do the same thing. Like I'd never do int x; // number of moons of Jupiter or something like that. But self-documenting code only goes so far.

¹ To make this a bit more concrete, it's about accurate to say that we were building up a string, but what we had was a callback function that, when called, we'd append another letter to the string. But some letters were computed based on the result of two successive calls. So we had to keep around some auxiliary information from the first call to use in the second, then detect whether we were in a "normal" case, the first call of one of these special cases, or the second call of one of these special cases. (I also kept around some additional state to sanity check that the callback was giving us things in the right order.)

This. A million times this. It doesn't matter if you know the code like the back of your hand right now. I can almost guarantee you that
if you stop working on it for any reasonable amount of time (3 - 6 months), you'll probably forget a large portion of what your code was
actually doing.

I document the API (I usually program against an interface) of whatever code I'm working on. If I come back to the code after some period
of time, I can take a quick look and understand what my code does without having to scroll through several lines of implementation details.

If something needs explaining why we're doing something, I'll document it. I used to put in comments when a particular function "got too long"
but then I realized that the better way was to split that out into a private function with a descriptive name. This made the implementation
details self documenting, and it helped prevent any one function from being too long to hold in your memory.

[sourmìlk]

I don't know why, but figuring out what I wrote is, for whatever reason, much more appealing to me than commenting. I hate commenting. It feels like a waste of time, even if it isn't. I'd much rather spend that time relearning code than commenting.