8 ms·

What incenses me is this recent notion that because programmers fail to change comment with the code change, they shouldn't even write comments. They should ins

What incenses me is this recent notion that because programmers fail to change comment with the code change, they shouldn't even write comments. They should instead write the self-documenting code. This doesn't make sense on so many levels. Only a recluse sitting in some dungeon who never dealt with people can come up with something so inane. Edit: I understand that that every developer should aspire to become someone who writes code that reads like a children's book, and they should. However, actively discouraging writing comments is so wrong on so many levels. At the last place I worked, we used to have a small at-home coding test before interview and none of the young developers who successfully completed the test did any sort of code documentation or commenting. When I asked why, they would tell me that their code is self-documenting, which was utter nonsense.

emodendroket 8y ago
Obviously code is never entirely self-documenting, but I think the idea is that, given the choice between something obscure with comments and something obvious on its face, you should prefer the latter unless there is some compelling rationale not to.
- phakding 8y ago
  I understand that that every developer should aspire to become someone who writes code that reads like a children's book, and they should. However, actively discouraging writing comments is so wrong on so many levels. At the last place I worked, we used to have a small at-home coding test before interview and none of the young developers who successfully completed the test did any sort of code documentation or commenting. When I asked why, they would tell me that their code is self-documenting, which was utter nonsense.
  - emodendroket 8y ago
    Well, this is a classic problem with people taking a guideline and applying an extreme version without understanding the rationale. I had a meeting one time where someone suggested that a code review went much easier when the submitter used remarks on the PR to explain what it did, and I suggested that if they were helpful during review they'd be helpful later, so just using comments would be better. He replied to me that that didn't make sense because comments are a code smell (a term I've kind of come to detest).
cessor 8y ago
I found this technique to work quite well, but this idea does not mean imply that one should simply "quit writing comments", but rather that comments can most often be replaced with actual structures that improve the code (e.g., extracting long boolean expressions into a function with the same name as the actual comment), but that also depends on the language and aptitude of the developer. Would you really argue in favor of something like this? ``` class Account { ... /// returns the accountId public int d_nr() { ... } } ``` ``` class Account { ... /// returns the accountId public int getAccountId () { ... } } ``` The first comment is obsolete when using a proper method name, the second does that and so the comment is redundant. May I ask: What did you experience in the wild?
- scarface74 8y ago
  Or even better don’t return an int return an “accountId” type.
  - jokerx 8y ago
    Please don't do this! All you have accomplished really is to move the descriptive name from the variable's name to the variable's type, and at what cost? You now have to create a whole new datatype. The programmer must look up that datatype and see oh, it's just an int. And now you need conversion routines or worse yet casting to convert that type to a simple int for interop reasons (database, UI). Experience has shown that it is very productive to have a small number of generally useful datatypes which are augmented by custom datatypes. Creating a new datatype for something as simple as an int or String defeats that and makes it more cumbersome to work with. (It's especially unwarranted for a variable that is an immutable variable serving as a simple id.)
    - scarface74 8y ago
      You haven’t just moved the descriptive name from the variable name to the type. If you are using a strongly typed language, you can just right click on the accountId type and find everywhere in your codebase where the “accountId” is being used. The “accountId” is not “just an int”. An accountId has semantics that would be different than an int. An accountId is not the same as a “customerId” that may also be represented as an int. The accountId also has different uses than an int. You’re not going to take the sum, average, etc of an accountId. An accountId that happens to have a value of 1 is semantically not equivalent of a customerId of 1. A method that expects a list of accountIds that are just ints will just as happily take a list of customerIds. But a method that takes as a parameter List<AccountId> will cause a compile time error if you pass in a List<CustomerId>. Why use a strongly typed language and then ruin one of the benefits of it if you don’t use domain specific types?
bausshf 8y ago
I want to clarify that when you're writing frameworks you sometimes need to document even self-documenting code. That's because some document generators will exclude functions that doesn't have document attached.

emodendroket 8y ago

Obviously code is never entirely self-documenting, but I think the idea is that, given the choice between something obscure with comments and something obvious on its face, you should prefer the latter unless there is some compelling rationale not to.

phakding 8y ago
I understand that that every developer should aspire to become someone who writes code that reads like a children's book, and they should. However, actively discouraging writing comments is so wrong on so many levels. At the last place I worked, we used to have a small at-home coding test before interview and none of the young developers who successfully completed the test did any sort of code documentation or commenting. When I asked why, they would tell me that their code is self-documenting, which was utter nonsense.
- emodendroket 8y ago
  Well, this is a classic problem with people taking a guideline and applying an extreme version without understanding the rationale. I had a meeting one time where someone suggested that a code review went much easier when the submitter used remarks on the PR to explain what it did, and I suggested that if they were helpful during review they'd be helpful later, so just using comments would be better. He replied to me that that didn't make sense because comments are a code smell (a term I've kind of come to detest).

cessor 8y ago

I found this technique to work quite well, but this idea does not mean imply that one should simply "quit writing comments", but rather that comments can most often be replaced with actual structures that improve the code (e.g., extracting long boolean expressions into a function with the same name as the actual comment), but that also depends on the language and aptitude of the developer. Would you really argue in favor of something like this? ``` class Account { ... /// returns the accountId public int d_nr() { ... } } ``` ``` class Account { ... /// returns the accountId public int getAccountId () { ... } } ``` The first comment is obsolete when using a proper method name, the second does that and so the comment is redundant. May I ask: What did you experience in the wild?

scarface74 8y ago
Or even better don’t return an int return an “accountId” type.
- jokerx 8y ago
  Please don't do this! All you have accomplished really is to move the descriptive name from the variable's name to the variable's type, and at what cost? You now have to create a whole new datatype. The programmer must look up that datatype and see oh, it's just an int. And now you need conversion routines or worse yet casting to convert that type to a simple int for interop reasons (database, UI). Experience has shown that it is very productive to have a small number of generally useful datatypes which are augmented by custom datatypes. Creating a new datatype for something as simple as an int or String defeats that and makes it more cumbersome to work with. (It's especially unwarranted for a variable that is an immutable variable serving as a simple id.)
  - scarface74 8y ago
    You haven’t just moved the descriptive name from the variable name to the type. If you are using a strongly typed language, you can just right click on the accountId type and find everywhere in your codebase where the “accountId” is being used. The “accountId” is not “just an int”. An accountId has semantics that would be different than an int. An accountId is not the same as a “customerId” that may also be represented as an int. The accountId also has different uses than an int. You’re not going to take the sum, average, etc of an accountId. An accountId that happens to have a value of 1 is semantically not equivalent of a customerId of 1. A method that expects a list of accountIds that are just ints will just as happily take a list of customerIds. But a method that takes as a parameter List<AccountId> will cause a compile time error if you pass in a List<CustomerId>. Why use a strongly typed language and then ruin one of the benefits of it if you don’t use domain specific types?

bausshf 8y ago

I want to clarify that when you're writing frameworks you sometimes need to document even self-documenting code. That's because some document generators will exclude functions that doesn't have document attached.