1

This question already has an answer here:

I use Xcode to edit my source files, and typically a file will look like this

//
//  Queue.swift
//  SomeCompany
//
//  Created by Someone (Job Title) on 26/06/2017.
//  Copyright © 2017 SomeCompany. All rights reserved.
//

/// A queue is a list where you can only insert new items at the back and remove items from the front. 
/// This ensures that the first item you enqueue is also the first item you dequeue. 
/// First come, first serve!
struct Queue<T> {
    ...
}

Are comments at the top of a source file a bad idea? The bit I am specifically talking about is:

  • The filename
  • The company name
  • The author, and the date it was created
  • The copyright information

I am rather dubious about the whole thing since all of the information is available in git, except the copyright information.

I would prefer the whole thing to be trimmed.

//
//  Copyright © 2017 SomeCompany. All rights reserved.
//

/// A queue is a list where you can only insert new items at the back and remove items from the front. 
/// This ensures that the first item you enqueue is also the first item you dequeue. 
/// First come, first serve!
struct Queue<T> {
    ...
} 

Work colleagues think I am being irrational as they believe original author is useful to know who originally created the file, and when they created it - but my argument is that it becomes out of date as soon as someone edits it (plus, all that information is available in vcs anyway)

I want to know if it seems sensible to get rid of the filename, company and author information.

marked as duplicate by gnat, David Arno, Bart van Ingen Schenau, Robbie Dee, amon Aug 30 '17 at 11:12

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

  • IMHO: You need the copyright, company name & any legalese (usually disclaimers) required in your jurisdiction. Anything else is optional. – NWS Aug 30 '17 at 9:38
  • 3
    In my view this is purely opinion-based. I hate, hate, hate having to wade through any sort of comments before I get to the code. Others like explanatory comments. Still others seem to love polluting their code with copyright guff (which, as far as I know, can be put into a separate file and have it satisfy any jurisdiction). – David Arno Aug 30 '17 at 10:02
3

Once upon a time before file versioning, keeping basic header information such as what the class does, when it was created, and by whom was somewhat necessary. If something didn't work, you needed to be able to contact the programmer that made it if, for no other reason, than to give him a thorough telling off.

Nowadays, file versioning has done away with most of this information, but old habits die hard. It may still even be useful to provide a brief summary of what the class or file does/defines, as nobody is going to kill you in your sleep for writing excessive comments though you may get a few eye rolls.

My thoughts are that if headers are present throughout a project, it is better to be consistent, even if you think it is silly and unnecessary. Otherwise, focus on making the code clear and concise rather than filling the lines inbetween with commentary. Only if the code is unclear (may the programming gods save us all) should you write a few lines explaining it to the best of your ability.

  • 2
    how does VCS answer the "what does it do" question? – Nick Keighley Aug 30 '17 at 10:50
  • 2
    @NickKeighley, the code should answer the "what does it do?" question. Writing comments to explain bad code is not really a very good substitute for writing better code. – David Arno Aug 30 '17 at 11:07
  • 1
    @NickKeighley The question isn't about documentation. Documentation is sensible. The question is about meta-information like copyright, license, authorship, change tracking, file name, …. – amon Aug 30 '17 at 11:08
  • code rarely answers the "what does it do" in my observation. I prefer a comment explaining what a class is for. – Nick Keighley Aug 30 '17 at 14:22
  • The comment I was responding to specifically mentioned "what the class does". – Nick Keighley Aug 30 '17 at 14:23

Not the answer you're looking for? Browse other questions tagged or ask your own question.