EntropySink

Technical & Scientific => Programming => Topic started by: micah on June 02, 2015, 10:54:31 AM

Title: The importance of small, well-commented commits and inline code commenting
Post by: micah on June 02, 2015, 10:54:31 AM

A project manager just asked me to find out why a "JD Power" callout box was missing from certain pages of a website.  While it should have been his job to know why, it sure as hell helped that I write useful comments on everything I do and make source control commits often.  I was able to quickly find both *when* the change was made and more importantly, jog my memory as to *why.*

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: Mike on June 02, 2015, 11:33:14 AM

I like to link people to this blog post about git commit messages: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: ober on June 02, 2015, 07:42:41 PM

What is a jd power callout anyways?  I saw a reference to that in some code once and didn't understand the reference.

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: charlie on June 02, 2015, 11:29:36 PM

Quote from: micah on June 02, 2015, 10:54:31 AM

A project manager just asked me to find out why a "JD Power" callout box was missing from certain pages of a website.  While it should have been his job to know why, it sure as hell helped that I write useful comments on everything I do and make source control commits often.  I was able to quickly find both *when* the change was made and more importantly, jog my memory as to *why.*

Love that stuff...

Boss: Why did you make that change to the application? It doesn't make sense!
Employee: I've attached the email thread you sent me last month where you asked me to make that change. It also happens to include the part where I told you it doesn't make sense.

I also have co-workers who are constantly worried about making mistakes. Then they'll message me about something they're fixing and comment about how somebody made some dumb mistake. I look up what happened and I see it was that person who made the mistake, but I don't say anything because I don't want to make them feel bad (and I don't care who messed up). The best part is later in the day they'll send a message, "doh! that was me." Good times.

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: Mike on June 02, 2015, 11:51:20 PM

If you know how to ask it git will tell you all the dirty secrets.  But seriously, having some sort of paper trail is a must.

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: kermi3 on June 03, 2015, 11:33:10 AM

Quote from: charlie on June 02, 2015, 11:29:36 PM

"doh! that was me." Good times.

Sign of a good co-worker

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: Mike on June 03, 2015, 11:50:36 AM

When I got back to VIE I was like "Who wrote this crappy code? <git blame> Damn it, it is my crappy code!"

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: charlie on June 03, 2015, 08:39:19 PM

One drag about working in the same code for 15 years is that you see your shit from 15 years ago that still has your name on it.

Title: Re: The importance of small, well-commented commits and inline code commenting
Post by: ober on June 05, 2015, 11:16:53 PM

Yeah, commit histories are both a godsend and an annoyance depending on the situation.