Hacker News new | past | comments | ask | show | jobs | submit login

> reject the idea you have to write any comments where the code is ‘self explanatory’

I'm one of those, but in your defense I think we need to maintain a very high bar for "self explanatory".

At the same time, I think it's important to be aware that comments not immediately adjacent to what they describe are usually not visible in code review, are often not visible to the person editing the code in question, will fall out of date without an active process to keep them up to date, and at that point will do more harm than good.

I'm curious if you have any particular mechanisms for addressing the above?

I'm trying in my current setting by introducing a mechanism for cross-references (anywhere in the repo, ^^{label} refers to @@{label}) that my CI setup can recognize and surface during code review. It's provided a bit of benefit, but it's underused, and it's too soon to have a good sense of long term impact.




>> I'm one of those, but in your defense I think we need to maintain a very high bar for "self explanatory".

I put 'self explanatory' in square quotes exactly because of that, at the time of writing the code many things may seem self explanatory for the person writing it, but even seemingly simple things can be very confusing for people who read the code for the first time. But obviously I'm not advocating comments that simply describe in words what the next line of code does mechanically, those are useless. But I do like comments that break up the algorithm in sections that are clearly marked by comments, even if some parts of those comments may seem trivial ('loop over all objects of type x and process those with property y', etc). For me the value is in being able to read the comments first and get an idea of the structure of the code and the though process behind it, before actually having to interpret the code itself.

>> At the same time, I think it's important to be aware that comments not immediately adjacent to what they describe are usually not visible in code review [..] I'm curious if you have any particular mechanisms for addressing the above?

Not really. In our team we don't really use code review tools for feedback about algorithms or higher level design of the code, my experience they are pretty awful for that anyway. We use bitbucket primarily to point out local improvements and ask questions why sections where added or changed, but for higher-level discussion we prefer offline tools like whiteboarding, and rotating people so everyone works on different parts of the codebase.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: