Same as the `widthInPixels` example really, but my pet peeve is always around units of time. Don't comment that `timeout` variable, just rename it `timeoutMillis`, `timeoutSecs`, or whatever it is.
If possible in your language, I'd say that you should also replace name by types: using the name widthInPixels won't help you if you do widthInPixels = widthInMilimeter, but a strong type would prevent this.
A good point, but I'd like to add that the bigger the visibility scope of a variable, the more relevant this advice is. In method scope you will be perfectly fine with a primitive type and a descriptive name. In a bigger scope you might consider hiding the type as the implementation detail.
Even better if you are using something like F#, which has the concept of units built into the language, so you can't mistakenly add feet and centimeters together without converting first.
Same as the `widthInPixels` example really, but my pet peeve is always around units of time. Don't comment that `timeout` variable, just rename it `timeoutMillis`, `timeoutSecs`, or whatever it is.
ReplyDeleteAnd using the correct type. Why using an int for timeout if you could use a TimeSpan? It exposes the unit of time directly at the moment you use it.
DeleteIf possible in your language, I'd say that you should also replace name by types:
ReplyDeleteusing the name widthInPixels won't help you if you do widthInPixels = widthInMilimeter, but a strong type would prevent this.
A good point, but I'd like to add that the bigger the visibility scope of a variable, the more relevant this advice is. In method scope you will be perfectly fine with a primitive type and a descriptive name. In a bigger scope you might consider hiding the type as the implementation detail.
DeleteAmen, Jay. Timeouts should be described in their units and this should extend all the way to the user interface/command line.
ReplyDeleteAll real-world physical quantities should be described or typed with their units.
Even better if you are using something like F#, which has the concept of units built into the language, so you can't mistakenly add feet and centimeters together without converting first.
DeleteGreat advice! It's all about explaining the why, because code can often hide that.
ReplyDeleteThanks for the excellent blog post.
Also, could you add the Code Health label to this? So it shows up with the other Code Health posts? Seriously loving this series.
Done! Thanks for the heads up!
ReplyDeletei think the timeoutMillis`will be more perfect .
ReplyDeleteThis is really helpful and awesome practice to comment only when it is really required.
ReplyDelete