5 ms·

When I interview for jobs, one of the questions I ask is where the team and engineering org stand on code comments and what state of documentation do they have

by mlthoughts2018 8y ago

When I interview for jobs, one of the questions I ask is where the team and engineering org stand on code comments and what state of documentation do they have for legacy code. It's a good question because people will use excuses like IP protection to avoid talking about the ugly truth of the state of their actual code, but if you're just asking about comments and documentation, there's no reasonable way they can deflect the question. If they won't answer it, well, you've got your answer. Any place that takes an attitude of "code should be self-documenting" I just walk away from. That is a type of dysfunction you're not gonna be able to solve. Also places that say, "we're always evaluating new ways to improve documentation practices..." begs further questions to get the specifics out of them. For most jobs, I know I'm going to have to deal with bad legacy code. But if there is also a culture of not documenting things, arguing against comments or formatted API and function documentation, and it results in documentation spaghetti of Google docs, Markdown files, spreadsheets, emails, confluence pages, etc., then there's no point. I can't help you.

scient 8y ago
So you're saying cant read existing code in order to understand it, or you just wont? Not arguing that self-documenting code is a good excuse for not documenting anything, but if you have to write an essay to go with your code, maybe the code itself is not that great?
- otras 8y ago
  This is an odd false dilemma you’re presenting here. I don’t think that GP was claiming an essay along with the code is a good option or an indicator of great code, and that’s certainly not the only other option than self-documenting code.
- mlthoughts2018 8y ago
  That’s a false dichotomy though. There is a middle ground where you write concise, purposeful documentation regularly and try to automate and centralize it as much as possible. Occasionally, for very tricky algorithms or business logic, yes, you may need a few paragraphs in a comment to make it clear why something is happening. Especially if you take the perspective that you’re writing it for junior / unfamiliar readers, and not for people who could glean it from the code itself. But most of the time we’re just talking about concise function docstrings, a few lines about what a certain class is intended for. Most documentation won’t be essays. It’s also not about whether your code “needs” documentation or comments. The code should be clean and no more complex than required, always, and refactoring is to help do that over time. That has almost nothing to do with providing comments or documentation for future people who could be inexperienced, unfamiliar with that programming language, unfamiliar with that type of algorithm, coming to the source file many years after the last time it was edited, etc. The reasons to need documentation are many, and even if the code “is so good it doesn’t need comments” that usually does not matter at all to the person reading the code, and that person still does need comments. Thinking of comments as an indicator of inferior code is a dangerous code golf mentality that ignores the fact that you write comments _for people_, especially people coming to the code in a way that breaks all the assumptions the code author was thinking when they decided not to write comments.
- IshKebab 8y ago
  Some code is complex enough to need a proper explanation. Maybe you just haven't encountered any. I guess it would be rare in CRUD or web apps, but when you start getting into algorithms... Look at Ryu for example. Good luck understanding that without comments or documentation: https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c
- u801e 8y ago
  No matter how well the code is written, without comments, understanding why it was written is going to be difficult to determine.
jpalomaki 8y ago
Self-documenting code typically can answer "How", but not always "Why"
ozim 8y ago
I don't care about comments, I care about unit tests and I need to run trough code with debugger. If code is testable I can run piece of code in isolation and understand how it works. Most of the time people do comments: a = 4 //assign value 4 to a Of course that is exaggeration but usually they restate obvious things and think it is good comment. Also I don't trust comments, I have to see commit history, and if I see there was piece of code changed where comments are, without stepping through and debugging I don't trust code is doing what comment is saying. I do not know how other people are writing code, but I have to run code locally, ideally in unit test or click through in the interface with test data. Maybe others just can run code in their heads and account for what is written in comments. But unfortunately I am not human compiler/runtime/processor.
- crazygringo 8y ago
  > Most of the time people do comments: a = 4 //assign value 4 to a When I see people arguing against comments, I see this strawman again and again and again. In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. It's not "most of the time" that people comment like that, in my experience it's never. Programmers have a job to do, and in my experience generally do not waste their time using comments to "restate obvious things and think it's a good comment". Rather, they comment when necessary to explain the why, or to provide a concise 2-sentence description that would be too long for a function name but lets you skip reading the next 30 lines of code which would take much longer. I really wish people would stop using this strawman of "most comments are redundant/obvious anyways, therefore don't comment". I mean, maybe you personally did have the terrible luck to work with a codebase that was actually like that... but I personally have never seen it.
  - ergothus 8y ago
    > but I personally have never seen it. I have. That said, I think we are on the same position on the issue. When I've seen such comments, it's when someone that didn't understand the value if comments is responding to a request to ask them. Thus is not necessarily because they are being deliberately obtuse, but because they never really experienced helpful comments. To me, 90% of the time a good comment wont say what's happening, instead it will say WHY it is happening. If good coding practised makes the code itself clear, good coding practice makes the context the code is written in clear. But for those new, and/or those too use to a particular codebase or just never exposed to good comments, they wont get it, and when asked to do one (either as a general request or in a code review) the strawman is what you get (usually not as ridiculous as this example, but equally useless). I see it as a cycle when learn to code: first we find comments useless so we skip them where we can. Then thus becomes normal, so we are used to seeing no or only useless comments. Then one day we look at code that we know we were confused on before but have forgotten why. On the N-th time of this, we leave the one line comment that says the secret. On the N plus one-th time, we read that comment and are enlightened. We then spend years trying to figure out the magic behind a useful and a useless comment, and arguing with those who think only useless comments exist.
p0nce 8y ago
Heard strange stories about a 30 person company where comments _were disallowed by policy._ I can't even imagine what kind of other problems this place would have.
- shodan666 8y ago
  I worked few years ago for Accenture (biggest consulting company on Earth) writing some SQL/Python for one of the largest European Bank. I was forbidden to use ANY code comments as well. I was also criticized when i proposed the idea of automatic code testing... I quit after 13 months.
- yesenadam 8y ago
  I imagine they weren't allowed to talk about their problems...
jandrewrogers 8y ago
Code comments must be a balancing act because they are not free. Documentation for its own sake is not an unalloyed good if the value does not justify the cost. You are fighting entropy here, so maximizing documentation value generated for minimum programmer effort is important. Code should mostly be self-documenting in terms of the "how", and coding style, idioms, and guidelines should be enforced to ensure that the code actually achieves this goal. Importantly, a lot of implicit intent by the programmer can be made explicit through coding style alone. I prefer this method when possible because inferring programmer intent is one of the single biggest headaches for legacy code, and when intent is made explicit by the code itself you don't have to worry about the documentation diverging from the code nearly as much. I say "mostly self-documenting" because there are occasional cases where the "how" is not obvious even if the code is e.g. a specific result is guaranteed as a side effect of non-local state. The "why", on the other hand needs significant documentation to exist inline with the code, and you typically need two types of "why"s. First, for some things you need to explain why a specific implementation was chosen versus other possible implementations. Sometimes an implementation is arbitrary -- and I document this too, so people know it can be swapped out with minimal consequence -- but other times it was chosen to effect specific optimizations based on specific assumptions, both of which need to be documented so that a programmer can determine if the assumptions are still true. The other type of "why" is, of course, why does a specific bit of code need to exist at all? I've seen extremely innocuous code that fixed a subtle bug or edge case that would almost certainly be refactored away by a programmer some day if it wasn't explicitly documented that a tiny bit of logic was doing something very important. From an "80/20 Rule" perspective, I find that code styles the explicitly capture programmer intent, plus some well-written inline "why" documentation does most of the heavy lifting for code maintenance while minimizing the volume of documentation that has to be written and maintained by the programmers separate from code. There should also be some high-level documentation on design assumptions and scope, but programmers are less involved in that on a day to day basis.
- chrisweekly 8y ago
  IME (20 years in web-related software dev / arch / mgmt), the best ROI in this area comes from two things: - good commit messages - references to persistent requirements artifacts (eg Trello cards, Jira tickets, whatever) YMMV... but really doing these two things makes a huge difference.
GuB-42 8y ago
Maybe I am getting too familiar with bad code, but as I get more experienced, I tend to read comments less and less, sometimes actively avoiding them. Most of the comments I see are useless, outdated, or worse. Code, on the other hand, doesn't lie. Well commented code is nice, but there is no guarantee that comments match the code, it is better if code can be understood without the comments. This is a common problem in companies with coding rules that require a minimum comment/code ratio. People will write comments for the sake of writing comments. There will probably be also formal specification and design documents, user manuals, etc... That's great on paper, and the dev doing that will probably answer correctly to your interview questions. However, chances are they are all full of lies. Because, doing all that and keeping it up to date is really time consuming, and there are deadlines to meet. To put things simply, I've never worked on a well documented project. By well documented I mean that the documentation is better than grep. Some big open source project are good but I still sometimes end up with grep. The only part where people can be serious is in public API documentation.

scient 8y ago

So you're saying cant read existing code in order to understand it, or you just wont? Not arguing that self-documenting code is a good excuse for not documenting anything, but if you have to write an essay to go with your code, maybe the code itself is not that great?

otras 8y ago
This is an odd false dilemma you’re presenting here. I don’t think that GP was claiming an essay along with the code is a good option or an indicator of great code, and that’s certainly not the only other option than self-documenting code.
mlthoughts2018 8y ago
That’s a false dichotomy though. There is a middle ground where you write concise, purposeful documentation regularly and try to automate and centralize it as much as possible. Occasionally, for very tricky algorithms or business logic, yes, you may need a few paragraphs in a comment to make it clear why something is happening. Especially if you take the perspective that you’re writing it for junior / unfamiliar readers, and not for people who could glean it from the code itself. But most of the time we’re just talking about concise function docstrings, a few lines about what a certain class is intended for. Most documentation won’t be essays. It’s also not about whether your code “needs” documentation or comments. The code should be clean and no more complex than required, always, and refactoring is to help do that over time. That has almost nothing to do with providing comments or documentation for future people who could be inexperienced, unfamiliar with that programming language, unfamiliar with that type of algorithm, coming to the source file many years after the last time it was edited, etc. The reasons to need documentation are many, and even if the code “is so good it doesn’t need comments” that usually does not matter at all to the person reading the code, and that person still does need comments. Thinking of comments as an indicator of inferior code is a dangerous code golf mentality that ignores the fact that you write comments _for people_, especially people coming to the code in a way that breaks all the assumptions the code author was thinking when they decided not to write comments.
IshKebab 8y ago
Some code is complex enough to need a proper explanation. Maybe you just haven't encountered any. I guess it would be rare in CRUD or web apps, but when you start getting into algorithms... Look at Ryu for example. Good luck understanding that without comments or documentation: https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c https://github.com/ulfjack/ryu/blob/master/ryu/f2s.c
u801e 8y ago
No matter how well the code is written, without comments, understanding why it was written is going to be difficult to determine.

jpalomaki 8y ago

Self-documenting code typically can answer "How", but not always "Why"

ozim 8y ago

I don't care about comments, I care about unit tests and I need to run trough code with debugger. If code is testable I can run piece of code in isolation and understand how it works. Most of the time people do comments: a = 4 //assign value 4 to a Of course that is exaggeration but usually they restate obvious things and think it is good comment. Also I don't trust comments, I have to see commit history, and if I see there was piece of code changed where comments are, without stepping through and debugging I don't trust code is doing what comment is saying. I do not know how other people are writing code, but I have to run code locally, ideally in unit test or click through in the interface with test data. Maybe others just can run code in their heads and account for what is written in comments. But unfortunately I am not human compiler/runtime/processor.

crazygringo 8y ago
> Most of the time people do comments: a = 4 //assign value 4 to a When I see people arguing against comments, I see this strawman again and again and again. In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. It's not "most of the time" that people comment like that, in my experience it's never. Programmers have a job to do, and in my experience generally do not waste their time using comments to "restate obvious things and think it's a good comment". Rather, they comment when necessary to explain the why, or to provide a concise 2-sentence description that would be too long for a function name but lets you skip reading the next 30 lines of code which would take much longer. I really wish people would stop using this strawman of "most comments are redundant/obvious anyways, therefore don't comment". I mean, maybe you personally did have the terrible luck to work with a codebase that was actually like that... but I personally have never seen it.
- ergothus 8y ago
  > but I personally have never seen it. I have. That said, I think we are on the same position on the issue. When I've seen such comments, it's when someone that didn't understand the value if comments is responding to a request to ask them. Thus is not necessarily because they are being deliberately obtuse, but because they never really experienced helpful comments. To me, 90% of the time a good comment wont say what's happening, instead it will say WHY it is happening. If good coding practised makes the code itself clear, good coding practice makes the context the code is written in clear. But for those new, and/or those too use to a particular codebase or just never exposed to good comments, they wont get it, and when asked to do one (either as a general request or in a code review) the strawman is what you get (usually not as ridiculous as this example, but equally useless). I see it as a cycle when learn to code: first we find comments useless so we skip them where we can. Then thus becomes normal, so we are used to seeing no or only useless comments. Then one day we look at code that we know we were confused on before but have forgotten why. On the N-th time of this, we leave the one line comment that says the secret. On the N plus one-th time, we read that comment and are enlightened. We then spend years trying to figure out the magic behind a useful and a useless comment, and arguing with those who think only useless comments exist.

p0nce 8y ago

Heard strange stories about a 30 person company where comments _were disallowed by policy._ I can't even imagine what kind of other problems this place would have.

shodan666 8y ago
I worked few years ago for Accenture (biggest consulting company on Earth) writing some SQL/Python for one of the largest European Bank. I was forbidden to use ANY code comments as well. I was also criticized when i proposed the idea of automatic code testing... I quit after 13 months.
yesenadam 8y ago
I imagine they weren't allowed to talk about their problems...

jandrewrogers 8y ago

Code comments must be a balancing act because they are not free. Documentation for its own sake is not an unalloyed good if the value does not justify the cost. You are fighting entropy here, so maximizing documentation value generated for minimum programmer effort is important. Code should mostly be self-documenting in terms of the "how", and coding style, idioms, and guidelines should be enforced to ensure that the code actually achieves this goal. Importantly, a lot of implicit intent by the programmer can be made explicit through coding style alone. I prefer this method when possible because inferring programmer intent is one of the single biggest headaches for legacy code, and when intent is made explicit by the code itself you don't have to worry about the documentation diverging from the code nearly as much. I say "mostly self-documenting" because there are occasional cases where the "how" is not obvious even if the code is e.g. a specific result is guaranteed as a side effect of non-local state. The "why", on the other hand needs significant documentation to exist inline with the code, and you typically need two types of "why"s. First, for some things you need to explain why a specific implementation was chosen versus other possible implementations. Sometimes an implementation is arbitrary -- and I document this too, so people know it can be swapped out with minimal consequence -- but other times it was chosen to effect specific optimizations based on specific assumptions, both of which need to be documented so that a programmer can determine if the assumptions are still true. The other type of "why" is, of course, why does a specific bit of code need to exist at all? I've seen extremely innocuous code that fixed a subtle bug or edge case that would almost certainly be refactored away by a programmer some day if it wasn't explicitly documented that a tiny bit of logic was doing something very important. From an "80/20 Rule" perspective, I find that code styles the explicitly capture programmer intent, plus some well-written inline "why" documentation does most of the heavy lifting for code maintenance while minimizing the volume of documentation that has to be written and maintained by the programmers separate from code. There should also be some high-level documentation on design assumptions and scope, but programmers are less involved in that on a day to day basis.

chrisweekly 8y ago
IME (20 years in web-related software dev / arch / mgmt), the best ROI in this area comes from two things: - good commit messages - references to persistent requirements artifacts (eg Trello cards, Jira tickets, whatever) YMMV... but really doing these two things makes a huge difference.

GuB-42 8y ago

Maybe I am getting too familiar with bad code, but as I get more experienced, I tend to read comments less and less, sometimes actively avoiding them. Most of the comments I see are useless, outdated, or worse. Code, on the other hand, doesn't lie. Well commented code is nice, but there is no guarantee that comments match the code, it is better if code can be understood without the comments. This is a common problem in companies with coding rules that require a minimum comment/code ratio. People will write comments for the sake of writing comments. There will probably be also formal specification and design documents, user manuals, etc... That's great on paper, and the dev doing that will probably answer correctly to your interview questions. However, chances are they are all full of lies. Because, doing all that and keeping it up to date is really time consuming, and there are deadlines to meet. To put things simply, I've never worked on a well documented project. By well documented I mean that the documentation is better than grep. Some big open source project are good but I still sometimes end up with grep. The only part where people can be serious is in public API documentation.