4 ms·

> So even if comments are flawlessly updated they are not a silver bullet. This "has to be perfect in perpetuity or it is of no value" mentality I don't find h

> So even if comments are flawlessly updated they are not a silver bullet. This "has to be perfect in perpetuity or it is of no value" mentality I don't find helpful. Be kind to FutureDev. Comment the weird "why"s. If you need to change it later, adjust the comment.

bccdee 2y ago
Yeah: "what if this code becomes tech debt later" applies to everything, not just comments. It's a tradeoff. The best thing you can do to avoid creating debt for later maintainers is to write code that's easy to delete, and adding comments helps with that.
mnsc 2y ago
I don't think comments need to be perfect to have value. My point was that if a certain piece of code is solving a particularly confusing problem in the domain, explaining it in a comment doesn't _necessarily_ mean the code will be less confusing to future dev if the current developer is not able to capture the issue in plain English. Future dev would be happier I think with putting more effort into refactoring and making the code more readable and clear. When that fails, a "here be dragons" comment is valuable.
- MichaelZuo 2y ago
  They can write a very long comment explaining why it is confusing them in X, Y, Z vague ways. Or even multilingual comments if they have better writing skills in another lanaguage. And even if they don’t know themselves why they are confused, they can still describe how they are confused.
  - deleted 2y ago
    [deleted]
  - stouset 2y ago
    And any attempt whatsoever is some improvement over doing nothing and wishing luck to the next guy.
  - mnsc 2y ago
    And that time spent writing a small paper in one's native language would be better spent trying to make the code speak for itself. Maybe get some help, pair up and tackle the complexity. And when both/all involved is like, we can't make this any clearer and it's still confusing af. _Then_ it's time to write that lengthy comment for future poor maintainers.
    - Ma8ee 2y ago
      You can only do the “what” with clearer code. The “why” needs some documentation. Even if it is obvious what the strange conditionals do, someone needs to have written down that this particular code is there because the special exemption from important tariffs of cigarettes due to the trade agreement between Serbia and Tunis that was valid between the years years 1992 and 2007.
      - mnsc 2y ago
        This is where a good comment really can help! And in these types of domains I would guess/hope that there exists some project master list to crossref that will send both developers and domain experts to the same source for "tariff-EU-92-0578" specifically the section 'exemptions'. So the comment is not not just a whole paragraph copied in between a couple of /*/
chairmansteve 2y ago
Thing is, good documentation has to be part of the company's process. eg, a QA engineer would have to be responsible for checking the documentation and certifying it. Costs money and time. You can't expect developers, already working 60 hour weeks to meet impossible deadlines, to spend another 15 hours altruistically documenting their code.
- actionfromafar 2y ago
  Or you know, work the devs 40 hour weeks and make sure documentation is valued. Everything costs one way or another, it's all trade-off turtles all the way down.
- sanderjd 2y ago
  Don't let perfect be the enemy of good. "We don't write any documentation because we can't afford a dedicated QA process to certify it" <- that's dumb.
- yearolinuxdsktp 2y ago
  Every line of documentation is a line of code and is a liability as it will rot if not maintained. That’s why you should be writing self documenting code as much as possible that’s obviates the need for documentation. But unlike code, stale/wrong doc will not break tests. Spending 15 hours documenting the code is something no leader should be asking of engineering to do. You should not need to do it. Go back and write better code, one That’s more clear at a glance, easily readable, uses small functions written at a comparable level of abstraction, uses clear, semantically meaningful names. Before you write a line of documentation, you should ask yourself whether the weird thing you were about to document can be expressed directly in the name of the method of the variable instead. Only once you have exhausted all the options for expressing the concept in code, then, only then, are you allowed to add the line of the documentation regarding it.
  - RaftPeople 2y ago
    > Only once you have exhausted all the options for expressing the concept in code, then, only then, are you allowed to add the line of the documentation regarding it. But that's what people are talking about when talking about comments. The assumption is that the code is organized and named well already. The real world of complexity is way beyond the expressiveness of code, unless you want function names like: prorateTheCurrentDaysPartialFactoryReceiptsToYesterdaysStateOfSalesOrderAllocationsInTheSamePrioritySequenceThatDrivesFinancialReportingOfOwnedInventoryByBusinessUnit() The code that performs this function is relatively simple, but the multiple concepts involved in the WHY and HOW are much less obvious.

bccdee 2y ago

Yeah: "what if this code becomes tech debt later" applies to everything, not just comments. It's a tradeoff. The best thing you can do to avoid creating debt for later maintainers is to write code that's easy to delete, and adding comments helps with that.

mnsc 2y ago

I don't think comments need to be perfect to have value. My point was that if a certain piece of code is solving a particularly confusing problem in the domain, explaining it in a comment doesn't _necessarily_ mean the code will be less confusing to future dev if the current developer is not able to capture the issue in plain English. Future dev would be happier I think with putting more effort into refactoring and making the code more readable and clear. When that fails, a "here be dragons" comment is valuable.

MichaelZuo 2y ago
They can write a very long comment explaining why it is confusing them in X, Y, Z vague ways. Or even multilingual comments if they have better writing skills in another lanaguage. And even if they don’t know themselves why they are confused, they can still describe how they are confused.
- deleted 2y ago
  [deleted]
- stouset 2y ago
  And any attempt whatsoever is some improvement over doing nothing and wishing luck to the next guy.
- mnsc 2y ago
  And that time spent writing a small paper in one's native language would be better spent trying to make the code speak for itself. Maybe get some help, pair up and tackle the complexity. And when both/all involved is like, we can't make this any clearer and it's still confusing af. _Then_ it's time to write that lengthy comment for future poor maintainers.
  - Ma8ee 2y ago
    You can only do the “what” with clearer code. The “why” needs some documentation. Even if it is obvious what the strange conditionals do, someone needs to have written down that this particular code is there because the special exemption from important tariffs of cigarettes due to the trade agreement between Serbia and Tunis that was valid between the years years 1992 and 2007.
    - mnsc 2y ago
      This is where a good comment really can help! And in these types of domains I would guess/hope that there exists some project master list to crossref that will send both developers and domain experts to the same source for "tariff-EU-92-0578" specifically the section 'exemptions'. So the comment is not not just a whole paragraph copied in between a couple of /*/

chairmansteve 2y ago

Thing is, good documentation has to be part of the company's process. eg, a QA engineer would have to be responsible for checking the documentation and certifying it. Costs money and time. You can't expect developers, already working 60 hour weeks to meet impossible deadlines, to spend another 15 hours altruistically documenting their code.

actionfromafar 2y ago
Or you know, work the devs 40 hour weeks and make sure documentation is valued. Everything costs one way or another, it's all trade-off turtles all the way down.
sanderjd 2y ago
Don't let perfect be the enemy of good. "We don't write any documentation because we can't afford a dedicated QA process to certify it" <- that's dumb.
yearolinuxdsktp 2y ago
Every line of documentation is a line of code and is a liability as it will rot if not maintained. That’s why you should be writing self documenting code as much as possible that’s obviates the need for documentation. But unlike code, stale/wrong doc will not break tests. Spending 15 hours documenting the code is something no leader should be asking of engineering to do. You should not need to do it. Go back and write better code, one That’s more clear at a glance, easily readable, uses small functions written at a comparable level of abstraction, uses clear, semantically meaningful names. Before you write a line of documentation, you should ask yourself whether the weird thing you were about to document can be expressed directly in the name of the method of the variable instead. Only once you have exhausted all the options for expressing the concept in code, then, only then, are you allowed to add the line of the documentation regarding it.
- RaftPeople 2y ago
  > Only once you have exhausted all the options for expressing the concept in code, then, only then, are you allowed to add the line of the documentation regarding it. But that's what people are talking about when talking about comments. The assumption is that the code is organized and named well already. The real world of complexity is way beyond the expressiveness of code, unless you want function names like: prorateTheCurrentDaysPartialFactoryReceiptsToYesterdaysStateOfSalesOrderAllocationsInTheSamePrioritySequenceThatDrivesFinancialReportingOfOwnedInventoryByBusinessUnit() The code that performs this function is relatively simple, but the multiple concepts involved in the WHY and HOW are much less obvious.