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.
ВідповістиВидалитиAnd 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.
Видалити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.
ВидалитиAmen, Jay. Timeouts should be described in their units and this should extend all the way to the user interface/command line.
ВідповістиВидалитиAll 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.
ВидалитиGreat advice! It's all about explaining the why, because code can often hide that.
ВідповістиВидалитиThanks 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!
ВідповістиВидалитиi think the timeoutMillis`will be more perfect .
ВідповістиВидалитиThis is really helpful and awesome practice to comment only when it is really required.
ВідповістиВидалити