"Our code is self-documenting. If you need documentation then the code isn't written well enough"
-Assholes who don't know what it is like to work with mature code bases.
"Our code is self-documenting. If you need documentation then the code isn't written well enough"
-Assholes who don't know what it is like to work with mature code bases.
- People who don't know how to write clean code
- People who think that not only they figured out what 'clean code' even means, but that everyone else will agree, thus single-handedly ending some 50+ years of heated industry-wide debate, numerous billion-dollar attempts by some of the most talented people in the world, and troves of 8-dimensional mental gymnastics about design patterns by way of a $21 ebook, a code review and some blog posts
Not to mention thinking that clean sensible code is always an option. There will always be something. It could be a kernel bug, it could be a quirk of an external library, it could be just to get the bloody thing to link against static libraries, but there will always eventually be an issue that requires a workaround that doesn't make sense without context.
I agreed with this until my current job, when it was stated cheerfully by a guy whose code is so shit lousy that I want to do violence to him (an emotion I haven’t felt in probably ten years).
I think the book _Pragmatic Programmer_ explains the concept of this asshole type of programmer and how to have the same results as him without being an asshole yourself
I hope you are using someone else to judge how clean your code is. (Maybe you are, maybe it is). I have come across very little self documenting code outside of a textbook. Code is a very low level medium. In the meantime a comment can help save a lot of time.
Sorry, parent poster: Gotta agree w/ above comment here. With the minor warning that the unit tests are included in this. In a good environment, I should be able to go to the tests to understand not only WHAT the code is doing but WHY it's doing it. No matter how 'mature' the code base is.
In any mature code, there is going to be unintuitive code that only exists to work around an external issue beyond your control.
Recent example: when you authenticate to OpenSSH running on macOS 10.13 or 10.14, make sure to never attempt keyboard-interactive auth after password auth, or the server will stop responding.
Somewhere you need to write this fact down, so that the next person who comes across your auth code doesn't change the order of authentication methods.
You need to document things like that.
If you have a mature code base, you'll have dozens, or hundreds of these workarounds for all kinds of issues. If you look at the code, it'll seem inefficient. If you don't document why the code looks like it does, then someone will come along (possibly you) a few years in the future and "optimise" that line.
Sure, you could have a unit test that checks whether the workaround is in place. But then you STILL need to document why that unit test is there, or someone will come and consider it pointless and remove it.
or maybe they just didn't write the code? i mean, if it's mature it likely was a result of years of effort and many hands involved. some documentation is always better than none, lack of documentation is either laziness or dogma; neither of which is a valuable mindset when working on a team for a business.
Except when the documentation is out dated and has very little to do with the actual code. At that point you are better off without bad documentation than with it. I've wasted a lot of time solving strange bugs because the API had stayed the same as when the documentation was written, but the implications were totally different.
And it extends far beyond comments in source code. Don't be that person who people have to run to because he/she keeps everything in their head. It's not job security. Take some time and write things down for your future self and team members.
Ordinary people who go to buy a device can know what “version” a router or laptop/phone supports. It makes it much clearer when comparing two routers which supports newer technology rather than knowing the diff between .ac or .n
