re: 10 Principles of a Good Code Review VIEW POST

TOP OF THREAD FULL DISCUSSION
re: 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 w...
 

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