8 ms·

> Most comments in code are in fact a pernicious form of code duplication. Man, I used to work with a developer who, in basically all respects was a better dev

> Most comments in code are in fact a pernicious form of code duplication. Man, I used to work with a developer who, in basically all respects was a better developer than I am. But he was terrible for adding these type of pointless comments. When I'd point out in a review that his comment used the same 3 words as the code did in a different order he'd get all defensive.

wool_gather 6y ago
I'd rather my colleagues repeat themselves in their documentation comments than provide none at all. So I think the habit of writing those comments is more important than making sure that every single one has no repetition. I'm working in a codebase now that has a frustrating lack of documentation of important details. A data field called "imageURL" that's a string -- is that a remote or local URL? Where did it come from/how much can I trust that it's well-formed? (And why isn't it already an actual `ParsedURL` type?) Another datatype has three fields "name", "username", and "id", all strings, with no explanation of their purpose or differences. This means that I either have to track down the teammate that wrote the code and ask them every single time I run into something like this. Or I have to execute the whole program and reverse engineer the answer. Both are colossal wastes of time compared to a few "useless" or "repetitive" comments.
- disposekinetics 6y ago
  I had a teammate who would write something like the below and it drove me crazy. I assume this is closer to what the article meant. The below comment does not add anything to my understanding of what the program does. //Assign 5 to the val called a val a = 5;
  - wool_gather 6y ago
    Sure; that's a classic useless comment. Counterpoint would be a useful doc, where did the 5 come from? // Chosen by fair die roll. Completely random const kEschatonThreshhold = 5; val a = kEschatonThreshhold;
    - disposekinetics 6y ago
      Absolutely, that is a great comment.
- jaywalk 6y ago
  You're basically making the case that well-designed code doesn't need comments like the ones you're asking for.
  - wool_gather 6y ago
    Sure, if the name, type, and context of a variable can completely encode all the details that I need to know when working on the code, then fine, we can skip the doc comments. Do you think that's possible for every field in all, or even most, applications and languages? I do not. And so I don't think we should be allergic to a few wasted sentences of prose.
    - jaywalk 6y ago
      Of course it's not possible. And that's why the sane requirement for comments is to use them where something might not be obvious.
      - wool_gather 6y ago
        Sounds like we agree.
- andrepd 6y ago
  >A data field called "imageURL" that's a string -- is that a remote or local URL? Where did it come from/how much can I trust that it's well-formed? Put that information in your types and (i) you don't need to write those comments and (ii) the compiler can help you check if you haven't made mistakes.
  - wool_gather 6y ago
    I said "why isn't this a `URL` instead of a string". I know we should "Put that information in your types". The code is written. I can't safely make that change until I know the invariants, and if the person who wrote the code had written a doc comment, I would know them.
    - a1369209993 6y ago
      > The code is [already] written[ and doesn't include that information in its types]. By that logic, the code is already written and doesn't include that information in its comments, either. > if the person who wrote the code had written a doc comment, I would know [the invariants]. If you're going to ask that the person who wrote the code have written it differently, there's (in general, at least) no reason to ask for comments in preference to types.
- loup-vaillant 6y ago
  > I'd rather my colleagues repeat themselves in their documentation comments than provide none at all. To a point. Believe me, there are levels of repetition you would find less tolerable than a lack of documentation. Here's a real world example: we had a bunch of classes with lots of attributes. The getters and setters for those attributes were automatically generated (with a macro), because we had lots and lots of them. In the headers however, we wrote the prototypes in full, so the tools could find them more easily: Foo getFoo(); Bar getBar(); Baz getBaz(); void setFoo(const Foo &foo); void setBar(const Bar &bar); void setBaz(const Baz &baz); So far so good. Now documentation is an important thing. So important in fact that we had to document every single method in all classes. And since we were using Doxygen, we were a bit constrained. Foo getFoo(); ///< Get foo Bar getBar(); ///< Get bar Baz getBaz(); ///< Get baz void setFoo(const Foo &foo); ///< Set foo void setBar(const Bar &bar); ///< Set bar void setBaz(const Baz &baz); ///< Set baz OK that's redundant, not too bad, and QA is happy now. Well, no. First, we are supposed to be using Javadoc style documentation. Second, we need to document every arguments, and the return values. How are we supposed to understand a getter if we don't document its return value? /** * Get foo * * @return foo */ Foo getFoo(); /** * Get bar * * @return bar */ Bar getBar(); /** * Get baz * * @return baz */ Baz getBaz(); /** * Set foo * * @foo The new Foo */ void setFoo(const Foo &foo); /** * Set bar * * @bar The new Bar */ void setBar(const Bar &bar); /** * Set baz * * @baz The new Baz */ void setBaz(const Baz &baz); And so on, often for 20 attributes instead of just 3. I am not even kidding. Now we could say it's just a matter of space, but it isn't: sometimes, there was an attribute that was a bit special, and the comment reflected that: /** * Set wiz * * @baz The new Wiz. Must not be Merlin. */ void setWiz(const Wiz &wiz); Except the additional comment could as well be absent, because it was totally lost in the noise. I've missed several cogent pieces of information that way. Worse, the tech lead, who acknowledged that this practice was useless at best, and had the clout to have this restriction relaxed, refused to do so. To this day I'm not sure why. I have a couple hypotheses (plain inertia, don't fix what's not blatantly broken, don't want to argue with QA, afraid of regulation…), but nothing solid. If I had to chose between no comment at all and that, I'm not sure I would chose that. Sure, I would lose valuable comments, but if I already lost them because of sheer noise, I didn't lose much at all.
- VBprogrammer 6y ago
  I'm not arguing that good comments aren't useful. Of course even the best comment can later be invalidated by someone carelessly changing the code and failing to update that comment. However, that doesn't make pointless repetitive comments somehow better or more useful. For me comments should concentrate on the why and maybe the how but mostly ignore the what. That should be obvious from the code.
- UnFleshedOne 6y ago
  Would you be satisfied with a comment like that? :) string imageURL; // Url of an image
  - vincent-manis 6y ago
    string imageURL; // string variable containing the Url of an image
jaywalk 6y ago
//Insert new customer into database _db.Insert(newCustomer); The number of times I've had to point out how incredibly pointless comments like this are in code reviews is far too high. As is the number of times I've had to point it out to the same developer.
- pjc50 6y ago
  Worse is //Insert new customer into database _db.Insert(oldCustomer); As a reaction to this, I used to work somewhere that had a zero-comment policy. If you wanted to describe something you had to do it in the function and variable names. Overreaction in the other direction.
  - gregfjohnson 6y ago
    Absolutely agree. I had a similar experience. 30-character camel case names are no substitute for a well-written comment. What I've found works well is to view a comment as the topic sentence of a paragraph. For each section of code that can be reasoned about as a unit, set it off with white space above and below as paragraphs are set off in text, and give it a topic sentence explaining the intention. If there are difficult, delicate, or subtle aspects of the code, be kind to your reader and explain them.
- godshatter 6y ago
  I get that, but if there is a comment above each portion of the code with a short description of what they are attempting to do, then I don't mind that some of them are trivial. You can read the (hopefully syntax-highlighted) comments as a list of steps in the function. Also, maybe that was a large block of code that was replaced later with a function call. Or maybe the code used to validate things about the customer used to be there before the function call and now that's all been wrapped into the called function.

wool_gather 6y ago

I'd rather my colleagues repeat themselves in their documentation comments than provide none at all. So I think the habit of writing those comments is more important than making sure that every single one has no repetition. I'm working in a codebase now that has a frustrating lack of documentation of important details. A data field called "imageURL" that's a string -- is that a remote or local URL? Where did it come from/how much can I trust that it's well-formed? (And why isn't it already an actual `ParsedURL` type?) Another datatype has three fields "name", "username", and "id", all strings, with no explanation of their purpose or differences. This means that I either have to track down the teammate that wrote the code and ask them every single time I run into something like this. Or I have to execute the whole program and reverse engineer the answer. Both are colossal wastes of time compared to a few "useless" or "repetitive" comments.

disposekinetics 6y ago
I had a teammate who would write something like the below and it drove me crazy. I assume this is closer to what the article meant. The below comment does not add anything to my understanding of what the program does. //Assign 5 to the val called a val a = 5;
- wool_gather 6y ago
  Sure; that's a classic useless comment. Counterpoint would be a useful doc, where did the 5 come from? // Chosen by fair die roll. Completely random const kEschatonThreshhold = 5; val a = kEschatonThreshhold;
  - disposekinetics 6y ago
    Absolutely, that is a great comment.
jaywalk 6y ago
You're basically making the case that well-designed code doesn't need comments like the ones you're asking for.
- wool_gather 6y ago
  Sure, if the name, type, and context of a variable can completely encode all the details that I need to know when working on the code, then fine, we can skip the doc comments. Do you think that's possible for every field in all, or even most, applications and languages? I do not. And so I don't think we should be allergic to a few wasted sentences of prose.
  - jaywalk 6y ago
    Of course it's not possible. And that's why the sane requirement for comments is to use them where something might not be obvious.
    - wool_gather 6y ago
      Sounds like we agree.
andrepd 6y ago
>A data field called "imageURL" that's a string -- is that a remote or local URL? Where did it come from/how much can I trust that it's well-formed? Put that information in your types and (i) you don't need to write those comments and (ii) the compiler can help you check if you haven't made mistakes.
- wool_gather 6y ago
  I said "why isn't this a `URL` instead of a string". I know we should "Put that information in your types". The code is written. I can't safely make that change until I know the invariants, and if the person who wrote the code had written a doc comment, I would know them.
  - a1369209993 6y ago
    > The code is [already] written[ and doesn't include that information in its types]. By that logic, the code is already written and doesn't include that information in its comments, either. > if the person who wrote the code had written a doc comment, I would know [the invariants]. If you're going to ask that the person who wrote the code have written it differently, there's (in general, at least) no reason to ask for comments in preference to types.
loup-vaillant 6y ago
> I'd rather my colleagues repeat themselves in their documentation comments than provide none at all. To a point. Believe me, there are levels of repetition you would find less tolerable than a lack of documentation. Here's a real world example: we had a bunch of classes with lots of attributes. The getters and setters for those attributes were automatically generated (with a macro), because we had lots and lots of them. In the headers however, we wrote the prototypes in full, so the tools could find them more easily: Foo getFoo(); Bar getBar(); Baz getBaz(); void setFoo(const Foo &foo); void setBar(const Bar &bar); void setBaz(const Baz &baz); So far so good. Now documentation is an important thing. So important in fact that we had to document every single method in all classes. And since we were using Doxygen, we were a bit constrained. Foo getFoo(); ///< Get foo Bar getBar(); ///< Get bar Baz getBaz(); ///< Get baz void setFoo(const Foo &foo); ///< Set foo void setBar(const Bar &bar); ///< Set bar void setBaz(const Baz &baz); ///< Set baz OK that's redundant, not too bad, and QA is happy now. Well, no. First, we are supposed to be using Javadoc style documentation. Second, we need to document every arguments, and the return values. How are we supposed to understand a getter if we don't document its return value? /** * Get foo * * @return foo */ Foo getFoo(); /** * Get bar * * @return bar */ Bar getBar(); /** * Get baz * * @return baz */ Baz getBaz(); /** * Set foo * * @foo The new Foo */ void setFoo(const Foo &foo); /** * Set bar * * @bar The new Bar */ void setBar(const Bar &bar); /** * Set baz * * @baz The new Baz */ void setBaz(const Baz &baz); And so on, often for 20 attributes instead of just 3. I am not even kidding. Now we could say it's just a matter of space, but it isn't: sometimes, there was an attribute that was a bit special, and the comment reflected that: /** * Set wiz * * @baz The new Wiz. Must not be Merlin. */ void setWiz(const Wiz &wiz); Except the additional comment could as well be absent, because it was totally lost in the noise. I've missed several cogent pieces of information that way. Worse, the tech lead, who acknowledged that this practice was useless at best, and had the clout to have this restriction relaxed, refused to do so. To this day I'm not sure why. I have a couple hypotheses (plain inertia, don't fix what's not blatantly broken, don't want to argue with QA, afraid of regulation…), but nothing solid. If I had to chose between no comment at all and that, I'm not sure I would chose that. Sure, I would lose valuable comments, but if I already lost them because of sheer noise, I didn't lose much at all.
VBprogrammer 6y ago
I'm not arguing that good comments aren't useful. Of course even the best comment can later be invalidated by someone carelessly changing the code and failing to update that comment. However, that doesn't make pointless repetitive comments somehow better or more useful. For me comments should concentrate on the why and maybe the how but mostly ignore the what. That should be obvious from the code.
UnFleshedOne 6y ago
Would you be satisfied with a comment like that? :) string imageURL; // Url of an image
- vincent-manis 6y ago
  string imageURL; // string variable containing the Url of an image

jaywalk 6y ago

//Insert new customer into database _db.Insert(newCustomer); The number of times I've had to point out how incredibly pointless comments like this are in code reviews is far too high. As is the number of times I've had to point it out to the same developer.

pjc50 6y ago
Worse is //Insert new customer into database _db.Insert(oldCustomer); As a reaction to this, I used to work somewhere that had a zero-comment policy. If you wanted to describe something you had to do it in the function and variable names. Overreaction in the other direction.
- gregfjohnson 6y ago
  Absolutely agree. I had a similar experience. 30-character camel case names are no substitute for a well-written comment. What I've found works well is to view a comment as the topic sentence of a paragraph. For each section of code that can be reasoned about as a unit, set it off with white space above and below as paragraphs are set off in text, and give it a topic sentence explaining the intention. If there are difficult, delicate, or subtle aspects of the code, be kind to your reader and explain them.
godshatter 6y ago
I get that, but if there is a comment above each portion of the code with a short description of what they are attempting to do, then I don't mind that some of them are trivial. You can read the (hopefully syntax-highlighted) comments as a list of steps in the function. Also, maybe that was a large block of code that was replaced later with a function call. Or maybe the code used to validate things about the customer used to be there before the function call and now that's all been wrapped into the called function.