ansaurus

Question

Program info; conventions, am I doing it right?

Answer 1

+1 A:

Theres no real convention that every programmer uses, provided you give all the information and keep the format consistent between all your code.

It sounds like your using some kind of doxygen format, however I'm pretty sure that it doesn't accept data at the start of files using '@'.

Personally, I would remove the '@'s so as to make it clearer to the browsing programmer, but thats just me. If you really need to reformat it later to comply with some other documentation generating program then if you do stick to something, it'll be simply to write a program that converts your source code to the required format. I'm pretty sure a lot of those programs can be modified to change what format they use as well.

Some people put a license all their code files but personally I keep my projects free of all that and use an automated program to fill it in before I release them.

So final answer, use something thats clear and constant to you.

Tomas Cokis 2010-09-30 05:27:32

I guess I was trying to please everyone else. Thanks for letting me know there's not really any specific format. I will do whats best for me since I'm pretty much the only one revising the code, I just document the code for my instructor to read pretty much. Thanks Tomas!

Kyle 2010-09-30 05:35:53

@Kyle, doxygen syntax is described at http://www.stack.nl/~dimitri/doxygen/docblocks.html. You're using JavaDoc syntax, which will make your life easier if you start working with both C++ and Java. Personally, I would make the file comment contain nothing but copyright information, maybe a \file, and move some of the @tags into the class documentation -- in the generated documentation, more people would look at the class documentation than the file. Use @author consistently, even if doxygen doesn't support it in some contexts.

Andy Thomas-Cramer 2010-09-30 13:15:46

Answer 2

+1 A:

Consider giving the short description of the module as the first line of the comment. It is a good practice to include the email id of the original author, so that future maintainers can contact him. You may also want to include copyright and licensing information:

/**
* Stack overflow question!
* Copyright (C) 2010 Kyle <[email protected]>
* Date: 9-29-2010 
*/

Vijay Mathew 2010-09-30 05:42:06

I like that format. Thank you:)

Kyle 2010-09-30 08:08:14

ansaurus

tags:

views:

answers:

Program info; conventions, am I doing it right?

related questions