Discussion on: What are common myths about software careers?

erhankilic profile image
Erhan Kılıç

I agree with you about automated tests, yes. But I've never seen before a self-documented code unless code's job are simple :)

Thread Thread
rhnonose profile image
Rodrigo Nonose

Code is self-documented by definition.

Documentation is an explanation of the code. You can explain the how and why of the code. The "how" is self-evident by the code, but the "why" could be up to interpretation and misleading.

The only reason to document anything should be to explain "why". There's no better way to explain "how" by a readable code and meaningful names, which is not hard but it'll always be consistent.

The "why" could be simple as you pointed out and there's no need for documentation. But also explaining "why" in the code shouldn't be necessary if the code is clean and good (also hard).