[makecheck]

Over the years I’ve concluded, reluctantly, that the ONLY documentation solutions that matter are the code, revision control logs and issue trackers.

Create massive comment blocks to explain things if you have to but put it all there in the code, next to the things that matter. Then it has half a chance of still being accurate. And, you know exactly where the documentation is. If the code becomes obsolete and is removed, you naturally strip out documentation that is no longer relevant at the same time.

Revision control log messages are important. I so hate lazy messages; if you change 5 files in random ways and your message is “fixed bug”, I think you should be fired. If it’s in the issue tracker, your log had better mention the number. Add a paragraph daring to explain what the hell you did so I can read a sensible log history and figure out what happened when.

Issue trackers are useful for capturing every relevant detail, especially new information that is found while the bug is being investigated. The bug might come up again, and details can help to sort it out.

[pugworthy]

You are assuming this is a tool for developers. It can be for anyone organized as a team, or based around a product.

A product for example has sales, marketing, support, development, and more. They could all coexist in a single stack centered around the product for example.

[makecheck]

Those all sound like things that should be in perfect sync with the implementation. It would kind of suck if Marketing started talking about one way things work, when they actually work differently. The company sure as hell shouldn’t have Sales selling people based on things that aren’t true.

As I said in another comment, information extracted from code can be made more pretty but ideally the code is king.

[pugworthy]

No you totally want marketing to be talking about something in the same place, even if they are wrong. It would absolutely not suck if they posted something incorrect, because then the people that know better can post alternative answers and/or comment and help correct the information.

If you put them in separate stacks, the bad information will just persist and live in isolation, and never get corrected.

You basically want to do everything you can to prevent silo'ing of people as well as knowledge. You want people talking.

Consider too that not everything posted has to be about technology. It can be recommendations for a good restaurant near a customer site, or where office supplies can be found in a large, multi-site office, or how to request facilities to come fix a leaking faucet.

[monkeydust]

Lol. Your kidding right. This would definitely be useful as a communication layer between business and sales with perhaps engineering involved.

[sametmax]

How do you fit deployment doc in code ? And tutorials ? General graphs of the architecture ?

Because an API reference is a very poor doc.

[aeorgnoieang]

Ideally your deployments are code. And tutorials are part of your website 'code', or integrated into your project (and thus 'code'). General graphs of the architecture would be docs in your code repo (and thus 'code' too). I'll admit tho that it's pretty sensible to just not consider some of those as 'code' and thus conclude that documentation outside of the code is important too.

But the original commenter is also probably right that 'second hand' documentation is probably the least accurate.

[makecheck]

These documents are still things that can become out of date. Anything of this nature can be in a source file somewhere, even if it’s a giant overview comment in one of the main files.

I do think it’s fine to create pretty docs from source comments or generate pictures from graph descriptions, etc. Every generated page should clearly state where it came from though (e.g. revision number and date).

Frankly I don’t like having only an API doc without the implementation. Code should be open-source to those using it, under NDA if necessary. When I need to rely on hidden implementations from Apple, etc. I routinely have to waste time discovering things simply not working as described. Meaning, their pretty docs are out of sync with reality and it wastes significant time to find this out the hard way.

[matt4077]

And yet, Stack Overflow has been massively successful.

I also doubt that anyone could efficiently learn, say, CSS just by reading the Firefox source, revision history, and bugzilla.

[snarf21]

The conclusion I've come to in regards to comments is that each function should have a comment about WHY it is needed. As you said the code will change and exactly what it does will morph, but the why describes the architecture (somewhat) and hints at the abstraction model.

[chatmasta]

Please no, do not comment every function. Each function should average 5-10 lines, with clearly defined separation of concerns, and a descriptive name that inherently describes any writes/reads of the function. In the rare case where it makes sense to have a massive function, and you can’t break it into smaller functions within its scope, then maybe it makes sense to use a comment.

Adopting a policy of commenting every function header creates two major problems: (1) you now need to edit a comment every time you change a function, but your editor/compiler/rcs/ci will not inform you if you forget; (2) introducing a “typing tax” on creating new functions, since you need to write a comment too, actually discourages writing small functions because of the required comments.

The most readable code does not need comments, because you can clearly infer what each small function does by reading its header and local variable names. When looking at a set of functions, i.e. a class or file, you should be able to infer the “why” of each function by seeing it in the context of the other sensibly-named functions surrounding it.

Personally, my commenting policy is very simple: if I cannot infer the behavior of a piece of code by reading it, and I cannot change it to be more readable (usually for efficiency purposes), then I write a short comment explaining whatever is strange about it. This way someone reading through the code doesn’t need to slow down when they get to the grotesque portion, because they can just read the comment, assume it’s correct and double check later if necessary. Whereas if the code is littered with comments, you really can’t assume any are correct, which makes it difficult to read the actual code.

[your-nanny]

I agree, except i think you missed parents point, which was to document why the function was being written, not what the code _does_

[your-nanny]

Is this philosophy of code commenting the antithesis of literate programming?