Information script,code

Pipelines
1

Hey all,

What kind of information do you add on the top of your script file?

What I do now is :

  • name of programmer
  • last time updated
  • goal of the script,code

What else do you add there?

Greetings,

Nysuatro

2

We used to post author, time, etc. at the top of our scripts, but not anymore. Perforce, like similar tools, has a standard for marking-up source files that get checked in, to fill that sort of info out, but we found that it was annoying when doing diffs/merges. Most of that info is available easily in Perforce/source control, where they all go anyway.

Instead, we just use a standard docstring header at the top (of our Python files). Looks like this:

 
"""
Enter a description of the module here.
 
*Examples:*
 Enter usage examples here. (optional field)
 
*Todo:*
 * Enter thing to do. (optional field)
 
*Author:*
 * Joe Himdickel, joe.himdickel@volition-inc.com, 3/30/2011 7:49:32 AM
"""

We use Wing IDE to insert those, which automatically fills-out the username, email and timestamp. They’re written in REST format so we can use them for documentation builds using Sphinx.

We have similar standard headers for classes and functions.

3

That is very interesting. Thanks for sharing

4

I also like to add the version of software. (eg: Maya 2011, or python 2.7, etc…)

5

We normally just throw some info at the top about what it’s for and what it does. If it has any ‘to-do’ items, or specifically unsupported behaviour that goes in too.

Generally though, versions, authors etc don’t go in as we use perforce for that kind of information. Many of our tools are altered/updated/written by multiple people so it’s hard to pin a single author as a tool progresses through production. That way knowledge is shared and if one person is not in for a period of time the rest of the TA’s can always offer support.

6

Same as above answers. All that traditional info should be in p4- who’s done what, changelist history, etc. If you need a ‘change log’ in the file, you need better changelist descriptions! If it were a python module I’d have a docstring like Adam says. I do feel todo lists are better kept in a backlog system (or inline comments) rather than at the top of a file, though.

7

Thanks for the information.

I once noticed people using xml for placing this kind of data on the top of the script files. Someone knows what the idea is behind this? I guess this is linked to a database system.

8

[QUOTE=Nysuatro;9935]I once noticed people using xml for placing this kind of data on the top of the script files. Someone knows what the idea is behind this? I guess this is linked to a database system.[/QUOTE]

There are many documentation-creating frameworks that use these XML tags as the basis of their automatically generated documentation.

9

We used to use RCS tags from P4 in everything but as mentioned they can make diffs awkward. So in general they were gutted – an exception being that some files are maintained where their revision and date strings contain values that are displayed in "about"dialog boxes and the like. But they are a very small minority of files, and those RCS tags are easily identified as being inside string constants.