Commenting Best Practices

  • (2 Pages)
  • +
  • 1
  • 2

16 Replies - 1360 Views - Last Post: 05 August 2015 - 06:53 AM

#1 NeoTifa  Icon User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4081
  • View blog
  • Posts: 18,152
  • Joined: 24-September 08

Commenting Best Practices

Posted 04 August 2015 - 07:24 AM

Okay, so I had a question about best practices for commenting code. Am I wrong in saying that it's typical to write a block comment at the top of your files for new classes and such that would include the authors name and date created (and obviously description)? I have a template file for my classes and features and such, with my comment blocks. One of my coworkers is raising a huge hissy fit because I put my name on the files (though I suspect it's just because she's having a complex). Is this not okay?

######################################
# Created by [user] on [date]
#
# Step definitions for [feature].feature
######################################

###-Givens-###

###-Given Ands-###

###-Whens-###

###-When Ands-###

###-Thens-###

###-Then Ands-###



It's not much, but it's 100% more than was in any other suite. Just saying...

Is This A Good Question/Topic? 1
  • +

Replies To: Commenting Best Practices

#2 modi123_1  Icon User is offline

  • Suitor #2
  • member icon



Reputation: 13483
  • View blog
  • Posts: 53,820
  • Joined: 12-June 08

Re: Commenting Best Practices

Posted 04 August 2015 - 07:31 AM

I typically have a block, though not that fancy, at the top of files and classes outlining what they do, creation date, who created them, changes, who changed them, etc. It helps when I am cursing someone's existence in languages not heard for the last thousand years by man.
Was This Post Helpful? 0
  • +
  • -

#3 NeoTifa  Icon User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4081
  • View blog
  • Posts: 18,152
  • Joined: 24-September 08

Re: Commenting Best Practices

Posted 04 August 2015 - 07:41 AM

Aight, cool. Here's the inspiration for this post, and I just wanted to confirm that I am right. Sorry to rant.

Spoiler

Was This Post Helpful? 0
  • +
  • -

#4 tlhIn`toq  Icon User is offline

  • Xamarin Cert. Dev.
  • member icon

Reputation: 6507
  • View blog
  • Posts: 14,372
  • Joined: 02-June 10

Re: Commenting Best Practices

Posted 04 August 2015 - 07:41 AM

I haven't used (or seen) those kinds of comments in years. Different companies, different policies. If you check with 100 different companies/developers you'll get 100 different 'norms'. Unless every developer is going to add a comment at the top of the file to include their involvement I don't see much advantage in saying you created it. When 20 other people get done screwing around with it any resemblance to what you originally created will be purely coincidental. Yet when something they wrote breaks its got your name at the top of it.

Source control handles tracking of all the 'created by' and 'last opened by' data. Even who changed line 1541 on 04aug15 at 1330hrs along with what it looked like before and after the change. Let source control manage all the user involvement, who changed which blocks and so on. That's what its there for.
Was This Post Helpful? 3
  • +
  • -

#5 Skydiver  Icon User is offline

  • Code herder
  • member icon

Reputation: 5885
  • View blog
  • Posts: 20,092
  • Joined: 05-May 12

Re: Commenting Best Practices

Posted 04 August 2015 - 07:43 AM

View Postmodi123_1, on 04 August 2015 - 10:31 AM, said:

creation date, who created them, changes, who changed them, etc.


Assuming that people are using source control properly, is it still recommended to have this? Isn't all that information kept by your source control system? Or is this a case of, my IDE is smart enough to tell me the type of my variable, so don't use Hungarian notation, but my IDE is not smart enough to give me the file history, so be sure to put the file history in comments?

View Postmodi123_1, on 04 August 2015 - 10:31 AM, said:

It helps when I am cursing someone's existence in languages not heard for the last thousand years by man.

Been there, done that. Sometimes, it amusing to note that the individual has moved on to become a VP, director, or GM. :)
Was This Post Helpful? 0
  • +
  • -

#6 modi123_1  Icon User is offline

  • Suitor #2
  • member icon



Reputation: 13483
  • View blog
  • Posts: 53,820
  • Joined: 12-June 08

Re: Commenting Best Practices

Posted 04 August 2015 - 07:49 AM

*shrug* Sure, source control - now a days - probably has all that information in some form or another (abet less verbose), but if I am hopping through files it helps for a quick glance versus digging in the change history. Also I've been in environments where source control changes every couple of years so the chain of history breaks.
Was This Post Helpful? 0
  • +
  • -

#7 tlhIn`toq  Icon User is offline

  • Xamarin Cert. Dev.
  • member icon

Reputation: 6507
  • View blog
  • Posts: 14,372
  • Joined: 02-June 10

Re: Commenting Best Practices

Posted 04 August 2015 - 07:56 AM

Yep - but then we're really asking "Should we use comments as a way to band-aide over the real problem of poor source control implementation?"
I hate band-aides and would rather fix the source of the problem than to continually patch over a side affect.

Its way too easy for a person to just not put in a comment when they open a file - leaving the previous person holding the bag.
Are you going to add comments at every block of code you add? Source control makes those notations.
A person can very easily put someone else's name on a change if they have an axe to grind.

If you're going to use comments as versioning history then you have to take it seriously and rigorously or there is no point. At that point the volume of comments and the time taken to make them adversely affects the time to product the project. That's one reason automated tools are created in the first place.
Was This Post Helpful? 0
  • +
  • -

#8 modi123_1  Icon User is offline

  • Suitor #2
  • member icon



Reputation: 13483
  • View blog
  • Posts: 53,820
  • Joined: 12-June 08

Re: Commenting Best Practices

Posted 04 August 2015 - 08:07 AM

I would disagree. I find the usefulness, even if not 100%, better than lacking. As they say - different strokes, different folks.
Was This Post Helpful? 1
  • +
  • -

#9 NeoTifa  Icon User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4081
  • View blog
  • Posts: 18,152
  • Joined: 24-September 08

Re: Commenting Best Practices

Posted 04 August 2015 - 08:26 AM

That's why it's only the small block at the top. We use versioning control.
Was This Post Helpful? 0
  • +
  • -

#10 baavgai  Icon User is offline

  • Dreaming Coder
  • member icon


Reputation: 6979
  • View blog
  • Posts: 14,598
  • Joined: 16-October 07

Re: Commenting Best Practices

Posted 04 August 2015 - 08:57 AM

Not a big fan of code comments; I think it makes code harder to follow. ;)

However, as an historical record of changes on a given bit of code; yes. And you better put your name and date in there so I can track your ass down.

This does't happen in source code all that much: the source control will get the relevant comments.

But I have a ton of SQL objects with this kind of thing:
-- 05/01/2004 BAM: HR request, NJ only.  State kept for clarity.
-- 04/05/2004 KMS: Director request, HR and Director access added
-- 03/15/2004 BAM: Finance request, last residence added, social security added, security finance only.
-- 02/15/2004 KMS: Director meeting, HR request, last residence removed.
-- 12/30/2003 BAM: Finance request, last residence added.
-- 01/30/2003 BAM: Finance requested residents.  State added.
-- 01/03/2003 KMS: Finance requested only NJ residents.  State removed.  Zip code added.
-- 01/01/2003 BAM: Create for Finance: Employee, salary, state of residence.



Ten years later, someone will ask why the hell HR can see this report, why it only shows NJ, didn't it show all states before? Such a trail saves so much time and effort down the line. I insist on "getting that in email" for pretty much the same reason.
Was This Post Helpful? 0
  • +
  • -

#11 xclite  Icon User is offline

  • I wrote you an code
  • member icon


Reputation: 1237
  • View blog
  • Posts: 4,028
  • Joined: 12-May 09

Re: Commenting Best Practices

Posted 04 August 2015 - 08:59 AM

We don't track any versioning information in our source. The only documentation we want to see is the documentation that pertains to things I need to know to understand the code.

I remember having to maintain massive blocks like that when I was in defense, and I have to admit that I like leaving the versioning to version control. I don't want to have to spend time on code reviews making comments about the style of somebody's comments.
Was This Post Helpful? 1
  • +
  • -

#12 cfoley  Icon User is offline

  • Cabbage
  • member icon

Reputation: 2386
  • View blog
  • Posts: 5,009
  • Joined: 11-December 07

Re: Commenting Best Practices

Posted 04 August 2015 - 01:49 PM

My thoughts are:

  • Author gets logged in source control
  • Editors get logged in source control
  • Dates get logged in source control
  • Given-when-then belongs in BDD suite (which includes descriptions as Strings for when the tests fail)
  • I'm not sure what a "step definition" is but it sounds like it belongs in technical documentation.


However, the best thing to do is whatever the rest of the team does.
Was This Post Helpful? 0
  • +
  • -

#13 Skydiver  Icon User is offline

  • Code herder
  • member icon

Reputation: 5885
  • View blog
  • Posts: 20,092
  • Joined: 05-May 12

Re: Commenting Best Practices

Posted 04 August 2015 - 01:55 PM

And when migrating between source control systems, either take the extra 2-5 days it takes to research and implement migrating project history; or find a way to keep the legacy system alive for archival purposes; or clone the history into an intermediate DVCS repo like git or Mercurial, but have the project start from a well known starting point so as not to carry too much baggage around.
Was This Post Helpful? 1
  • +
  • -

#14 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10681
  • View blog
  • Posts: 18,289
  • Joined: 19-March 11

Re: Commenting Best Practices

Posted 04 August 2015 - 02:15 PM

View Postmodi123_1, on 04 August 2015 - 09:31 AM, said:

I typically have a block, though not that fancy, at the top of files and classes outlining what they do, creation date, who created them, changes, who changed them, etc. It helps when I am cursing someone's existence in languages not heard for the last thousand years by man.



git blame.


Quote

*shrug* Sure, source control - now a days - probably has all that information in some form or another (abet less verbose), but if I am hopping through files it helps for a quick glance versus digging in the change history.


magit, baby. full-power git porcelain, in your emacs. Done.
Was This Post Helpful? 0
  • +
  • -

#15 jon.kiparsky  Icon User is offline

  • Chinga la migra
  • member icon


Reputation: 10681
  • View blog
  • Posts: 18,289
  • Joined: 19-March 11

Re: Commenting Best Practices

Posted 04 August 2015 - 02:22 PM

View Postxclite, on 04 August 2015 - 10:59 AM, said:

I don't want to have to spend time on code reviews making comments about the style of somebody's comments.



This wins. So many more reasons to get rid of comments, but this is, in itself, plenty of reason to not have the noise blocks.

For me, a comment is a code smell: it usually means you're doing something wrong, and probably you need to fix something. In this particular case, if you're keeping version history in the source code, that's a huge problem: it means you're not using source control, or you're not using it correctly. (I remember one job where we were using svn, but there was a custom commit system, which obliterated history. I suggested reverting to a normal command line or tortoise interface, and they looked at me like I had three heads.... I didn't stay there all that long)
Was This Post Helpful? 1
  • +
  • -

  • (2 Pages)
  • +
  • 1
  • 2