[CentralOH] [Dojo] Concerning code comments

[Damien Calloway]

Hello,

First of all, we have a Python dojo that meets on Thursday nights
starting @ ~ 6pm at Smokehouse Brewery :
https://www.smokehousebrewing.com/



1130 Dublin Road Columbus, Ohio 43215
 614.485.0BBQ (0227




I have reason to believe that this Thursday is "Sauerkraut Ball Night" -
it may be quite busy
========================

Now, at said dojo, a discussion came up last week about code comments.
Jim Prior felt that code comments were a "code smell" - that one should
write code in such a way that it does not require comments.
I looked into this philosophy (as Jim also demonstrated some refactoring
that supported his view) - the rabbit hole around commenting is deeper
than I thought. I find them useful to document things, but Jim mentioned
that there were better, more effective ways to accomplish that.
I wanted to see how widespread this belief was.

There were a series of posts on Coding Horror - these grabbed my
attention, as Jeff Atwood is one of the co-founders of Stack Overflow.
He also created one of the best Markdown tutorials I have seen.

https://blog.codinghorror.com/when-good-comments-go-bad/

https://blog.codinghorror.com/coding-without-comments/

https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/

This was very eye-opening, but I thought "Well, surely, there must be
*some* use for comments... how does the code get documented ?"
Then I read this : "Common Excuses Used To Comment Code, and What To Do
About Them"
http://www.codeodor.com/index.cfm/2008/6/18/Common-Excuses-Used-To-Comment-Code-and-What-To-Do-About-Them/2293
This article is literally a point-by-point rebuttal of nearly every
reason one could think of for using comments  - including several
insights for team environments (i.e. - your teammates should be able to
get information from the commit messages instead of the code comments.
And anyway, it is a version control system - use it !)
In his view, code comments are only needed in four situations : 

 1. In the styles of Javadoc, RubyDoc, et cetera for documenting APIs
    others will use. <-- Not every day that you write a API. And perhaps
    a Markdown document would be better ?
 2. In the off chance it really is that complex: For example, on a
    bioinformatics DNA search function that took 5 weeks to formulate
    and write out. That's how rare it is to have something complex
    enough to warrant comments. <--- Python has a *lot* of modules....
    can we just import a problem that someone else solved ?
 3. TODOs, which should be the exception, not the rule <---- This to me
    is reasonable
 4. Explaining why the most obvious code wasn't written. (Design
    decisions) <------ This is interesting as well. I thought all
    code should be commented for this reason, but, well.... maybe
    not so much.
I will have an opportunity to test out this hypothesis - as well as TDD
- on my much-delayed Pomodoro timer project. Speaking of which, I also
came across :
https://code.joejag.com/2018/two-line-budget.html  <--- Your two line budget for tests
Mind you, I found this right after I found the first two links - it
seems that the "write the code so that you don't have to comment it"
applies to tests, too, in my mind. I always wondered how tests would get
refactored as time goes on and projects get larger, and this was my
answer, apparently.
As far as how to write good tests, I found this :
http://www.blog.j-labs.pl/2017/02/Given-When-Then-pattern-in-unit-tests
This was helpful, because of the screenshots showing what they mean. 

Oh, and as far as rebuttals ? The ones I found seemed to come mostly
from enterprise developers, government contractors, and people who have
to work with rank beginners or outsourcing. At that point, though, you
get into team dynamics, communication issues, politics, and a whole
bunch of "Layer 8" issues that actually have nothing to do with code.
- Damien




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/centraloh/attachments/20180808/6d58cf34/attachment.html>