Graduated in Digital Media M.Sc. now developing the next generation of educational software. Since a while I develop full stack in Javascript using Meteor. Love fitness and Muay Thai after work.
Should code be written in a way that's expressive enough on it's own?
The majority of my code is written as expressive as possible. Especially naming of variables, functions, interfaces and classes can already have a great impact here.
Note that this is also a great responsibility for the architects and lead engineers who design and model the software architecture. If they fail on their level to provide clear and understandable interfaces and APIs, you can't clean this mess up with expressible code.
If you disagree, what are your thoughts on keeping comments up to date with changes?
I would always comment parts of code where event minor changes can have big consequences, not matter whether the code is expressible or not. It's like the "STOP" or "DANGER" sign to cause attention.
And of course any externally consumed API is documented regarding it's functionality, expected input / output and potential exceptions.
Is there a grey area? Examples?
Hard to create definite "rules" on when code should be documented or not. I think a good indicator is when parts of the code are heavily discussed during a code review it should be documented with whatever was the controversy and how it got resolved.
Sounds like the entire thread has reached a consensus that comments do indicate mistakes but that sometimes mistakes and therefore comments are necessary.
And that the original statement is pretty accurate (except, sometimes it's also other peoples failures)
If you fail, then write a comment; but try not to fail.
I'd say lack of comments is a very clear indication of a pile of crawling creepy mistakes.
It's an indication of a wrong paradigm choice that lead to proliferation of a boilerplate code - all that code should have never existed in the first place.
It's an indication of a decision to forget all the important thought process that lead to the current code architecture, which will unavoidably lead to repeating the already made mistakes over and over again while maintaining this code in the future.
It's an indication of a lack of discipline in general, which, by proxy, results in a high number of bugs.
I'd stay as far away as possible from an uncommented code.
I'd say lack of comments [is] an indication of a wrong paradigm choice
Surely if your paradigm is correct, it easier to express without comments. I would say the exact opposite. Bad paradigm choice leads to need for comments to explain compromises made due to lack of express ability. Code is made closer and closer to English to make it more expressive, if you need to drop into English, the abstraction has failed to be expressive enough.
Even if your code reads just like plain English and it's as close to semantics of your problem domain as possible, it still only explains the "how" part. The "why?" part is missing.
The majority of my code is written as expressive as possible. Especially naming of variables, functions, interfaces and classes can already have a great impact here.
Note that this is also a great responsibility for the architects and lead engineers who design and model the software architecture. If they fail on their level to provide clear and understandable interfaces and APIs, you can't clean this mess up with expressible code.
I would always comment parts of code where event minor changes can have big consequences, not matter whether the code is expressible or not. It's like the "STOP" or "DANGER" sign to cause attention.
And of course any externally consumed API is documented regarding it's functionality, expected input / output and potential exceptions.
Hard to create definite "rules" on when code should be documented or not. I think a good indicator is when parts of the code are heavily discussed during a code review it should be documented with whatever was the controversy and how it got resolved.
Sounds like the entire thread has reached a consensus that comments do indicate mistakes but that sometimes mistakes and therefore comments are necessary.
And that the original statement is pretty accurate (except, sometimes it's also other peoples failures)
I'd say lack of comments is a very clear indication of a pile of crawling creepy mistakes.
It's an indication of a wrong paradigm choice that lead to proliferation of a boilerplate code - all that code should have never existed in the first place.
It's an indication of a decision to forget all the important thought process that lead to the current code architecture, which will unavoidably lead to repeating the already made mistakes over and over again while maintaining this code in the future.
It's an indication of a lack of discipline in general, which, by proxy, results in a high number of bugs.
I'd stay as far away as possible from an uncommented code.
Surely if your paradigm is correct, it easier to express without comments. I would say the exact opposite. Bad paradigm choice leads to need for comments to explain compromises made due to lack of express ability. Code is made closer and closer to English to make it more expressive, if you need to drop into English, the abstraction has failed to be expressive enough.
Even if your code reads just like plain English and it's as close to semantics of your problem domain as possible, it still only explains the "how" part. The "why?" part is missing.
yawn
This is what religious fanatics say when they're cornered. Uncle bob zealots are the worst of the worst, you're all beyond any redemption...