I’m Erhan Kılıç, a curious web developer from Turkey who loves to write software applications and websites.
I have been working as a web developer since 2013.
The larger the problem that the code resolves, the lesser the intelligibility of the code. Whatever you do, no matter how nice the code you write, this will not change.
How’s it going, I'm a Adam, a Full-Stack Engineer, actively searching for work. I'm all about JavaScript. And Frontend but don't let that fool you - I've also got some serious Backend skills.
Location
City of Bath, UK 🇬🇧
Education
10 plus years* active enterprise development experience and a Fine art degree 🎨
Code is self-documented. It's not good, readable or pleasant but a precise one.
Any code that you create without new/changed documentation makes the documentation obsolete. Also documenting something you made might not be correct because your assumptions can be wrong.
Also, automated tests are better documentation that any form of documentation because it actually runs the code (although it might run a different configuration of the code).
I’m Erhan Kılıç, a curious web developer from Turkey who loves to write software applications and websites.
I have been working as a web developer since 2013.
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).
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.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
"Code is self documenting"
Lie!!
The larger the problem that the code resolves, the lesser the intelligibility of the code. Whatever you do, no matter how nice the code you write, this will not change.
Could should be, I think aspiring is fine, expecting is something else altogether.
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 documentation makes the documentation obsolete. Also documenting something you made might not be correct because your assumptions can be wrong.
Also, automated tests are better documentation that any form of documentation because it actually runs the code (although it might run a different configuration of the code).
I agree with you about automated tests, yes. But I've never seen before a self-documented code unless code's job are simple :)
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).
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.