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.
OdpovedaťOdstrániť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.
OdstrániťIf possible in your language, I'd say that you should also replace name by types:
OdpovedaťOdstrániť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.
OdstrániťAmen, Jay. Timeouts should be described in their units and this should extend all the way to the user interface/command line.
OdpovedaťOdstrániť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.
OdstrániťGreat advice! It's all about explaining the why, because code can often hide that.
OdpovedaťOdstrániť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!
OdpovedaťOdstrániťi think the timeoutMillis`will be more perfect .
OdpovedaťOdstrániťThis is really helpful and awesome practice to comment only when it is really required.
OdpovedaťOdstrániť