Why would you not want to document your source code?

[Cogman]

This thread got so much deeper than I ever expected.

🙂 given a sufficient amount of time, any thread in the programming forum will eventually degrade to compiler optimizations and assembly :awe:

 

[Kr@n]

Back to topic, I probably am one of those that would comment "too much" (some code analyser app once told me ther was up to 40% of comment lines in my code) ...

Some snippets of my code might thus be a good argument for NOT commenting your code 😉 ...


NOTE : In my defence, I usually code at a higher level than the rest of the team. I thus have to comment that well (at least if I don't want to be bugged each time a change has to be made on that part of the code). One thing i found particularly stupid is to have very few comments, and not useful at that ("we then put that into this and compute foo&quot😉 ...

I begin most of my work by writing the layout of the algorithm in comments, and then write the code in-between. That usually makes it easy to avoid the traps of bad comments. Comments have to EXPLAIN what you do, not DESCRIBE it.

 

[Markbnj]

I begin most of my work by writing the layout of the algorithm in comments, and then write the code in-between. That usually makes it easy to avoid the traps of bad comments. Comments have to EXPLAIN what you do, not DESCRIBE it.

I often do that as well, but I replace most of the comments with code as I go along.

 

[KIAman]

It also depends on the complexity of the code as well. If the task was to write a 100 line simple sort or search algorithm, there really is no need to comment inside the code, that code should be pretty self documenting.

Other examples are event handlers that serve simple functions, such as a page redirect or a click event, or mouseover event, etc. The structure of the method is pretty much self documenting.

For complex projects, commenting and documentation become essential. A top down approach to development will follow a set of requirements, into a design, which lead to pseudo code, eventually into implemented code. I like to leave the pseudo code as comments inside the code. Not only does this provide good internal comments, but allows a second pair of eyes to verify the code matches the pseudo code.

This is especially the case once you start producing n-tier systems. I think Mark brought this up before but interfaces MUST be documented. Any time there is a coupling point in the design, that entrance and exit point must be documented with information on how the coupling works, performance requirements, timing requirements, availability, event handling, error handling, debug mode, etc.

So, my point is that commenting and/or documenting software is largely dependent on the complexity of the project.

 

[Kr@n]

It also depends on the complexity of the code as well. If the task was to write a 100 line simple sort or search algorithm, there really is no need to comment inside the code, that code should be pretty self documenting.

Sure, but I still think one would have to include some reference/link to a description of the said algorithm (or better yet, include it in the function header comment, and comment again tricky areas in the code, such as mathematical assumptions/proofs where needed). If there is a unexpected failure in the "simple" sort 6 years later (access violation, segfault, leak, whatever) and the only available dev is far from a math/algo master, your code better be "over-commented", even if YOU find the code to be trivial.

I've been bitten enough by that back in the days (that would only be 5 years ago), when I thought portions of my code were self documenting (and my variables are in general very precisely named) ... Well, I found code is almost never self documenting (apart from one-liners, initializers, and such ...). No algo should stay undocumented.

Other examples are event handlers that serve simple functions, such as a page redirect or a click event, or mouseover event, etc. The structure of the method is pretty much self documenting

Yeah, I usually don't comment simple events (which tend to be the majority, for I don't like to write complex code in event handlers if I can avoid it - OOP for the win)


Even then, there's always this bizarre behaviour in one third party API or another, that you absolutely must comment ...