-
Notifications
You must be signed in to change notification settings - Fork 32
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Should provenance be recorded in the code files? #3
Comments
There are several reasons I think it is important to have the origin of each routine documented in the code:
That said, I can see that it may not be necessary to put this information into each function if the information is the same for a whole set of functions. If the text would be the same for all AWIPS functions, for instance, then perhaps it could be documented at the sub-module level only: i.e., in aos.awips. |
I added a comment giving my reasons for thinking this important under issue number 3. On Feb 15, 2013, at 10:00 PM, Johnny Lin wrote:
|
I think including a one line comment in the Python doc string stating where the original code came from may be appropriate. My initial comment was more concerning keeping bulky version information in the files. This information is available from the git commit history and is much easier to keep up to date and much harder to accidentally forget to update. I also think keeping a listing of where the various files originally came from for licensing, etc might be prudent. This could be included at the top of each file but may cause complication/work when comparing or updating these files with new version of the original. |
Jonathan H. wrote: "As for the provenance/version of the files, I would vote against including this information in the file themselves or a python docstring. I think that a betterplace for information like this belongs in the version control system (git) or a separate text file." I was wondering if Jonathan (and others who agree) could share why you feel this way. If provenance changes often I can see why this would be good, but for code that doesn't get changed very often, wouldn't it be a net plus to include where the code came from in the file?
The text was updated successfully, but these errors were encountered: