re: 10 Principles of a Good Code Review VIEW POST

FULL DISCUSSION
 

Hi Jason,

thanks for sharing your principles. It's really interesting to see how others are doing code reviews.

You have many valid points. But we are less strict when it comes to documentation (code should be self-expressive without comments; only comment when it adds value to the code) and the build-and-test-it-yourself-thing (as you already pointed out, CI systems help here).

However, I experienced that the human aspects of code reviews are extremely important. Giving feedback can be hard and can lead to hurt feeling and relationships when done wrong. Constructive code reviews require a certain mindset and phrasing techniques. I experienced this multiple times in my carrier. That's why I focused on those points in our Code Review Guidelines. Check it out, they may be a good addition to your principles.

 

Excellent guidelines, @philipp_hauer ! I'll include a link to that in the edit section of the article, in fact. It's worth linking to.

Unrelated, but "self-expressive" code is only ever capable of expressing what it does, never the programmer's intentions (the code's "why"). That's why I recommend CSI so strongly. In years of using it in production, I've seldom encountered an intent-comment which did not add value to the code. In other words, "why" comments are practically always useful, while "what" comments are virtually never useful.

 

In years of using it in production, I've seldom encountered an intent-comment which did not add value to the code. In other words, "why" comments are practically always useful, while "what" comments are virtually never useful.

I totally agree on this :) but I took slightly different approach: only comment "why" if it's not clear from the code (and method names, variable names, etc). Most of the "why" should be covered by tests (we're using BDD-style testing for this). Added benefit is that tests double as an up-to-date documentation

The only downside to relying on tests for this is that you have to leave the source to work it out, which greatly reduces your speed at learning the code.

I cover all these topics, including 'what vs. why' and 'comments vs. naming,' exhaustively in...

code of conduct - report abuse