re: What are common myths about software careers? VIEW POST

re: I disagree. Code is self-documented. It's not good, readable or pleasant but a precise one. Any code that you create without new/changed document...

You're semantically correct in that code documents itself because you can read the code and therefor know what it does. But that doesn't mean it's good. A car engine is self documenting because you can look at it, therefor anyone who drives can fix an engine. Somewhat contrived but still basically true for your argument I think.

Documentation and comments can and will fall out of date without proper care, but then we should be following the old adage that "comments document the why, not the how".

Yeah, kind what I outlined the "why" in the other response :)

But I don't agree with the engine analogy.

An engine is a unique piece that does one thing and one thing only, so the documentation is never deprecated (for that car model or that specific engine, unless you replace it).

What we typically see in software is someone hooking up a radio to the engine or putting shaders in the windshield while the car is running and stays there (in a web context let's say). It has a more dynamic nature than a pre-made component with standardized interface and replaceable like car parts.

If you have a piece of code that you never touch, sure, documentation is alright. But if you make a fix in the engine with non-standard practices, the car manual will fail you and you'll have to open up the engine anyway. This happens less frequently with cars but almost daily in software.

code of conduct - report abuse