How should one properly comment and license a set of code files before uploading to the public? [duplicate]

Question

I've written a decent chunk of code over the past few days and I'm ready to git init it and push it to github. But before I do so, I want to do this the "correct" way in case anyone else wants to use my code. So I guess I need to pick a license (probably MIT) and implement it, and write some sort of comment at the top of every file.

What is a good style comment to put at the top of the file? What info should it include, what should it look like? And do I put the license in a LICENSE folder in the root directory, or at the top of every source file or something? And are there any other steps I'm missing before throwing this up to github?

Answer 1

Short 2-line disclaimer should be enough, e.g.

// (c) 2011 Ricket
// This code is licensed under MIT license (see LICENSE.txt for details)

Don't forget that there is not much sense in publishing code if people can't found it, so write good description and readme (who knows when someone would need your code even if nobody comes on project page).

Answer 2

The disclaimer:

Copyright (C) [year] by [copyright holders]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without l> imitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

On the top of all source files and a separate LICENSE file on the project root. It sounds redundant but every step to make it clear the code licensing is a good step, at least for me.

Remember if/when you accept code contributions to track who submitted what. If someday you wish to change license, you'll need agreements with contributors or rewriting their code unless you require copyright attribution (may not be viable for smaller projects).

Answer 3

The other answers are the standard open-source legal disclaimer stuff that you see everywhere.

You need that.

But that is not all. Doing only the legal stuff is what drives me crazy with so much open source development.

Also put into the HEADER AT THE TOP OF THE FILE a description: - What this thing is (a short name) - Its purpose (a long description, the hows and whys of why this thing exists, pretend you are explaining to 6 year olds.)

Without those 2 things anybody looking at it has to read your mind to figure out what this stuff is, and if they are interested in it.

NEXT, you ask about commenting.

You should actually have been commenting as you wrote it, not post-fixing it in after the event.

But nevertheless, comments at the micro level just serve to waste everbodies time, and infuriate.

fred = fred + 1;    // increment fred

So, don't do that.

Instead, place a comment of substance before a chunk of code (not inside it!), setting out what the next thing does, being as general or specific as you need to be:

//
// This implements the fast integer line drawing algorithm originally by
// Fred Nurke (see http://www.nurkesoft.com/fild), with the following
// modifications for speed:
//  - Frangle the nurgulator before decrementing the frobber;
//  - Update the decrementer pointer once only.
//
// Having done that, dispatch it to the ice-age thread where it can sit and
// grow moss for a couple of decades.
//
<neat code comes here for perhaps 10 - 20 lines>

As a ROUGH generalisation, a lump of code running for more than about 20-30 lines is getting a bit too big - so this is the approximate size for a chunk that needs an explanatory leading comment. Almost all code will have chunks that are around 5 - 30 lines in a block with a comment suitable for that block. (That block performs some function or has some purpose that you can describe.)

And finally, comments should be nicely laid out, they should not use excessive or obscure acronyms, they should read as normal English, they should be grammatically correct and properly punctuated.