5 ms·

> Do not leave any other types of comments! Ever! Not even method docs. Have you ever looked at a very large project(blue whale as I'd like to call them)? In 1

> Do not leave any other types of comments! Ever! Not even method docs. Have you ever looked at a very large project(blue whale as I'd like to call them)? In 10 years time, 90% of the people who have worked on it initially will be gone from the company (or stopped contributing if it's an open source project). You are making everyone else's life a nightmare. To my mind the one project that got it bang on is postgres. It is by no means a library and the community's approach is perfect. Open up any of the source code files at random and you'll see what I'm on about. Just scrolling through the code and comments once will be enough for you to figure out exactly what is there and why.

echelon 6y ago
> Have you ever looked at a very large project > You are making everyone else's life a nightmare. I work on code touched by tens of thousands of other engineers. In my experience, code without comments is typically structured, easy to read, and does exactly what is written. Code painted top to bottom with comments tends to be muddied, confusing, and more junior in nature. The shape of solutions is common. You're not reinventing the wheel with every new project. Engineers are familiar with the design patterns, frameworks, and algorithms you use, so you don't need to force a context switch to point them out. You can use the symbols themselves as a form of documentation. Instead of having an entire algorithm inline, individual queries or processing steps might be put into their own self-documenting methods: verifyMarkdown(article_rating: &Rating) upsertRating(article_rating: &Rating, author: &User, transaction: &Transactor) publish(article_rating: &Rating, transaction: &Transactor) enqueueSubscriberNotifications(author: &User) Small pieces of code might not require a functions to wrap them, but by naming small units of behavior, you can communicate your algorithm step by step without comments. This is only one type of communication technique you can use. There are bountiful ways to improve your clarity. I apologize if my examples are obtuse. It's late.
- axegon_ 6y ago
  OK, good points, but my argument stands in most cases: It doesn't matter how experienced a developer is. You'll rarely see anyone as pedantic as I am when it comes to conventions, structure or organization, but there have been multiple instances when I've had to cut corners to meet some deadline. I work on an enormous projects with few developers. Say we all decide to go full Eric Cartman tomorrow and call it quits. Guess how long it's going to take someone else to work their way through 8 years of development without a single comment? My bet - they would keep hitting rocks day in and day out. In the case of thousands, the likelihood of everyone leaving at the same time is much lower, but I'll go back to my postgres example, which I genuinely use as a benchmark as far as code goes. If everyone abandons it today for some reason, everything is so well thought out, well structured and documented that new people can jump in right away and the development won't be slowed down dramatically, granted that the new developers follow the current process.
rootlocus 6y ago
> Have you ever looked at a very large project(blue whale as I'd like to call them)? Yes, I have. And almost none of the comments matched the code. My new "head of engineering" ruled that almost all lines of code must have matching comments. I now frequently find people changing the code but not the comments during code review.
- axegon_ 6y ago
  Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it.
  - seanwilson 6y ago
    - Comments aren't executed or covered by a test suite so it's much easier for mistakes in them to slip by. A comment like "Close the file when..." when it should say "Open the file when..." could easily slip by review or when the underlying code changes. Same with typos and wrong names. - When you're adapting existing code, misleadingly named variable names and function names are going to be quickly noticed and fixed as developers are forced to read them (unlike reams of external docs or big comments). If you name a function "close" instead of "open" by accident, someone is going to notice fast. > Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it. You can justify any misguided developer practice like this though. The question is "is this a worthwhile thing to spend time enforcing?" and not "is it possible to enforce?". Getting rid of manual checks is a good thing when you can too.
    - axegon_ 6y ago
      Things slip through inevitably but it's easy to correct them when you spot them eventually or am I missing something? That's what I do and that's what we've agreed upon with all developers and it's working flawlessly. This is turning into a philosophical question rather than a development one. What is worthwhile to begin with? As per Maslow's pyramid it's breathing, eating and drinking. I've had this argument with a former co-worker who was strictly against writing documentation and comments, precisely because it wasn't "worthwhile" and a "waste of time". "Right... Got anywhere to be right now or is your plan to finish your task till 11 and spend the rest of the day scrolling through facebook?" Common occurrence for that guy as a matter of fact. We've fought for years to take out the "we need that eod" to transition to long enough periods with realistic deadlines and plenty of time to spare for tests, documentation and so on. And it is something that we have now. It is proprietary software but the postgres example is perfectly valid - simply look at it.

echelon 6y ago

> Have you ever looked at a very large project > You are making everyone else's life a nightmare. I work on code touched by tens of thousands of other engineers. In my experience, code without comments is typically structured, easy to read, and does exactly what is written. Code painted top to bottom with comments tends to be muddied, confusing, and more junior in nature. The shape of solutions is common. You're not reinventing the wheel with every new project. Engineers are familiar with the design patterns, frameworks, and algorithms you use, so you don't need to force a context switch to point them out. You can use the symbols themselves as a form of documentation. Instead of having an entire algorithm inline, individual queries or processing steps might be put into their own self-documenting methods: verifyMarkdown(article_rating: &Rating) upsertRating(article_rating: &Rating, author: &User, transaction: &Transactor) publish(article_rating: &Rating, transaction: &Transactor) enqueueSubscriberNotifications(author: &User) Small pieces of code might not require a functions to wrap them, but by naming small units of behavior, you can communicate your algorithm step by step without comments. This is only one type of communication technique you can use. There are bountiful ways to improve your clarity. I apologize if my examples are obtuse. It's late.

axegon_ 6y ago
OK, good points, but my argument stands in most cases: It doesn't matter how experienced a developer is. You'll rarely see anyone as pedantic as I am when it comes to conventions, structure or organization, but there have been multiple instances when I've had to cut corners to meet some deadline. I work on an enormous projects with few developers. Say we all decide to go full Eric Cartman tomorrow and call it quits. Guess how long it's going to take someone else to work their way through 8 years of development without a single comment? My bet - they would keep hitting rocks day in and day out. In the case of thousands, the likelihood of everyone leaving at the same time is much lower, but I'll go back to my postgres example, which I genuinely use as a benchmark as far as code goes. If everyone abandons it today for some reason, everything is so well thought out, well structured and documented that new people can jump in right away and the development won't be slowed down dramatically, granted that the new developers follow the current process.

rootlocus 6y ago

> Have you ever looked at a very large project(blue whale as I'd like to call them)? Yes, I have. And almost none of the comments matched the code. My new "head of engineering" ruled that almost all lines of code must have matching comments. I now frequently find people changing the code but not the comments during code review.

axegon_ 6y ago
Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it.
- seanwilson 6y ago
  - Comments aren't executed or covered by a test suite so it's much easier for mistakes in them to slip by. A comment like "Close the file when..." when it should say "Open the file when..." could easily slip by review or when the underlying code changes. Same with typos and wrong names. - When you're adapting existing code, misleadingly named variable names and function names are going to be quickly noticed and fixed as developers are forced to read them (unlike reams of external docs or big comments). If you name a function "close" instead of "open" by accident, someone is going to notice fast. > Well that's an organizational problem. Personally when I do code review and I see a comment which is redundant or doesn't match the code, I immediately return the PR and tell the developer to fix it. You can justify any misguided developer practice like this though. The question is "is this a worthwhile thing to spend time enforcing?" and not "is it possible to enforce?". Getting rid of manual checks is a good thing when you can too.
  - axegon_ 6y ago
    Things slip through inevitably but it's easy to correct them when you spot them eventually or am I missing something? That's what I do and that's what we've agreed upon with all developers and it's working flawlessly. This is turning into a philosophical question rather than a development one. What is worthwhile to begin with? As per Maslow's pyramid it's breathing, eating and drinking. I've had this argument with a former co-worker who was strictly against writing documentation and comments, precisely because it wasn't "worthwhile" and a "waste of time". "Right... Got anywhere to be right now or is your plan to finish your task till 11 and spend the rest of the day scrolling through facebook?" Common occurrence for that guy as a matter of fact. We've fought for years to take out the "we need that eod" to transition to long enough periods with realistic deadlines and plenty of time to spare for tests, documentation and so on. And it is something that we have now. It is proprietary software but the postgres example is perfectly valid - simply look at it.