Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

In a few weeks, my project is going to be finished and I want to start getting my code ready for other people to use it.

I am going to be posting everything to GitHub so people can tweak it and hopefully make it better.

I guess what I'm asking is, what would be the best way to make sure my code is sufficiently documented and worded right for other people to use?

I know you should always comment everything and I'm going to be putting in the @params feature for every method, but are there any other tips in general?

share|improve this question
2  
possible duplicate of Preparing to release code as open-source –  Mark Booth Sep 20 '12 at 15:52
add comment

3 Answers

up vote 10 down vote accepted
  • Make sure there is a README.txt file in the root of the repository that points people to instructions on how to build it. The instructions could be in that file, or they could be in a separate file or wiki page.
  • Ideally, make it so that you can completely build and test the code with a single command. Don't require a bunch of manual steps.
  • Make sure you have tests for the code. This provides a convenient place for other developers to see how your code is used, plus it provides a safety net for people who modify your code. Knowing I can edit your code and then run a suite to see if I broke something is invaluable.
  • Follow common coding standards, or publish the ones you use.
  • If your code uses OO, make sure at least all public methods and attributes have sufficient documentation
  • Make sure it's clear what license your code uses. Typically this means to include a LICENSE.txt file, or follow whatever mechanism your specific license requires. Also, make a conscious choice about the license. Don't just use GPL because that's all you know. Likewise, don't just use BSD or MIT or Apache if that's all you're familiar with... spend an hour researching those so you at least understand the fundamental difference between GPL and non-GPL licenses.
  • Remove all sensitive information from the code, such as hard-coded usernames, passwords, email addresses, ip addresses, API keys, etc. (thanks to Hakan Deryal for the suggestion)
share|improve this answer
    
Good advice. Also another thing to add: Remove the private information like passwords/api keys if there are any. –  Hakan Deryal Sep 20 '12 at 14:38
    
If you have any sensitive information in the code, you might need to be careful to remove it from past commits as well (if you've already started using version control). An easy way to do that would be to create a completely new repository for the public version, but that might not be the best approach. –  yakiv Sep 20 '12 at 22:14
add comment

I guess what I'm asking is, what would be the best way to make sure my code is sufficiently documented and worded right for other people to use?

As open source, the most important comments of all are the copyright and license agreement comment. Rather than a big long comment at the start of every file, you might want to use a short and sweet one that briefly specifies copyright and refers the reader to license.txt in the root directory.

I know you should always comment everything and I'm going to be putting in the @params feature for every method, but are there any other tips in general?

Comment everything? No. Comment that code which truly does need commentary. Comment sparingly. As a potential user of a chunk of code, which of the following two versions of a class definition would you prefer to see?

Version A:

class Foo {
private:
   SomeType some_name; //!< State machine state

public:
   ...

   /**
    * Get the some_name data member.
    * @return Value of the some_name data member.
    */
   SomeType get_some_name () const { return some_name; }

   ...
};

Version B:

/**
 * A big long comment that describes the class. This class header comment is very
 * important, but also is the most overlooked. The class is not self-documenting.
 * Why is that class here? Your comments inside the class will say what individual parts
 * do, but not what the class as a whole does. For a class, the whole is, or should be,
 * greater than the parts. Do not forget to write this very important comment.
 */
class Foo {
private:

   /**
    * A big long comment that describes the variable. Just because the variable is
    * private doesn't mean you don't have to describe it. You might have getters and
    * setters for the variable, for example.
    */
   SomeType some_name;

public:
   ...

   // Getters and setters
   ...

   // Getter for some_name. Note that there is no setter.
   SomeType get_some_name () const { return some_name; }

   ...

};

In version A I've documented everything -- except the class itself. A class in general is not self-documenting. The comments that are present in version A are absolutely useless, or even worse than useless. That's the key problem with the "comment everything" attitude. That little terse comment on the private data member communicates nothing, and the doxygen comments on the getter has negative value. The getter get_some_name() doesn't really need a comment. What it does and what it returns is patently obvious from the code. That there is no setter -- you have to infer that because it's not there.

In version B I've documented that which needs commenting. The getter doesn't have a doxygen comment, but it does have a comment mentioning that there is no setter.

Make your comments count, and beware that comments oftentimes are not maintained to reflect changes to the code.

share|improve this answer
add comment

Documentation in source file is always good, but you should publish additional documentation on a website. Explain its goal, how it works, your future plans, try to make contribution easy (otherwise... nobody will help you) and put some tutorials.

Trying to work on a project with source code documentation only is always frustrating.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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