Great topic choice Michiel,
I'm honestly not 100% sure where I stand on this one - whats your opinion about aiming to write code that doesn't need comments but using them sparingly when needed for the particularly complicated stuff? Is it best to take an all or nothing approach or is that just something to strive for?
If it is up to me (as I will not go against code convention of the project) I will write only why if it can be explained in a few words, max 2 lines.
As for doc-comments (i.e. method/class comments) I will write pre- and post-conditions if the language does not support this in other ways. As I mostly develop in Java I do use the null-annotations. And for the rest I document it in the method. I generally also declare all exceptions it will throw, even unchecked exceptions.
So in the end: I will always try to write code, which will read like a (weird) story. And leave out footnotes (comments) as much as possible.
There is no all or nothing. Just aim to write as little (code and comments) as needed without sacrificing readability. (See other comments about this).
Sure thing, that seems like the sensible thing to do, nothing worse than going to read a comment in code and ending up trying to get through war and peace. Thats interesting what you say with regards to Java, I use PHP a bunch and have really enjoyed some of the new return type hinting improvements made in the latest versions precisely for the reason you mentioned. The other bonus of this is I find it also helps minimise the number of tests I have to write because the entry and exit criteria are much more controlled and behave more predictably.
Thanks for the answer!
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.
Great topic choice Michiel,
I'm honestly not 100% sure where I stand on this one - whats your opinion about aiming to write code that doesn't need comments but using them sparingly when needed for the particularly complicated stuff? Is it best to take an all or nothing approach or is that just something to strive for?
If it is up to me (as I will not go against code convention of the project) I will write only why if it can be explained in a few words, max 2 lines.
As for doc-comments (i.e. method/class comments) I will write pre- and post-conditions if the language does not support this in other ways. As I mostly develop in Java I do use the null-annotations. And for the rest I document it in the method. I generally also declare all exceptions it will throw, even unchecked exceptions.
So in the end: I will always try to write code, which will read like a (weird) story. And leave out footnotes (comments) as much as possible.
There is no all or nothing. Just aim to write as little (code and comments) as needed without sacrificing readability. (See other comments about this).
Sure thing, that seems like the sensible thing to do, nothing worse than going to read a comment in code and ending up trying to get through war and peace. Thats interesting what you say with regards to Java, I use PHP a bunch and have really enjoyed some of the new return type hinting improvements made in the latest versions precisely for the reason you mentioned. The other bonus of this is I find it also helps minimise the number of tests I have to write because the entry and exit criteria are much more controlled and behave more predictably.
Thanks for the answer!