Coding guidelines question
in [Fortran]
|
From: Bil Kleb on 14 Mar 2006 13:29 Paul Van Delst wrote: > > - Document all changes, not only around modified code but also in the > documentation block at the head of each subroutine or function. This is the job of your version control software. However, the thing you still have to record is the "why", not the "what". The "what" is chronicled ad nauseam by the version control software. The "why" is typically recorded in the log message that you are prompted for during checkin of a new version. I put myself in the "why" frame of mind by beginning each log entry with a prepositional phrase "To ..," For the die hard test-first folks, the "why" is recorded in executable code in the form of new tests that explicitly demonstrate why the changes had to be made to the production code -- see for example, the rather heavy-weight Aegis version control software <http://aegis.sourceforge.net>, which actually requires you to check in news tests with any source modifications! > - When modifying a routine, remember to add a one-line entry with change > date, programmer, and brief description. This one-line entry goes in > the program history log of the documentation block. Covered by the above, and don't be tempted to put a RCS/CVS tag like $Log$ in each file -- it creates a mess of meta data that is better managed by the version control software system. > - Ensure input/output argument documentation in doc block is consistent > with additions/deletions from calling list A lot of this can be obviated by using self-descriptive names, viz, http://c2.com/cgi/wiki?SystemOfNames > think the above requirements are a bit much - especially once we get > everyone using CVS (or Subversion) Agreed. Note: we've just switched from CVS to SVN primarily to be able to move files (and directories) without having to do a special jig to preserve it's revision history. FWIW, I have a canned talk on this whole team scientific software thing based on NASA TM 2003-212421: http://techreports.larc.nasa.gov/ltrs/PDF/2003/tm/NASA-2003-tm212421.pdf that I've been asked to give at various places like U of Michigan (CSEM), MIT (ACDL), U of Illinois (CSAR), U of Tennessee (SimCenter), etc., if you are interested. Regards, -- Bil Kleb http://fun3d.larc.nasa.gov
From: Bil Kleb on 14 Mar 2006 13:36 Pierre Asselin wrote: > > Since this was about coding standards, here are a few thoughts. > 1) Nobody likes coding standards, but if they get over it > they'll get over it. I speak from experience. > 2) Just make sure the standards are not harmful. I think > *mandating* USE at module level would be harmful. > 3) You need a mechanism to grant waivers, because you > can't be sure your standards won't be harmful rather > than just annoying. > 4) You need a mechanism to amend the coding standards, > for the same reason. 0) write the standard so that it encourages communication through code, e.g., use meaningful names, avoid complex code where simple code will do, apply the DRY principle, and use comments as a last resort and primarily to apologize for why the following code was written so unintelligibly. -- Bil Kleb http://fun3d.larc.nasa.gov DRY = Don't Repeat Yourself -- see http://www.artima.com/intv/dry.html
From: Paul Van Delst on 14 Mar 2006 14:48 Bil Kleb wrote: > Paul Van Delst wrote: > >> >> - Document all changes, not only around modified code but also in the >> documentation block at the head of each subroutine or function. > > > This is the job of your version control software. I know, however, I'm one of the few people that use version control here. We're changing that but, cripes, sometimes I wonder if it'll ever happen. > However, the thing you still have to record is the "why", not > the "what". The "what" is chronicled ad nauseam by the version > control software. > > The "why" is typically recorded in the log message that you > are prompted for during checkin of a new version. I put myself > in the "why" frame of mind by beginning each log entry with a > prepositional phrase "To ..," I do the why. What about folks that enter a log message such as "fixed a bug" and nothing else? It might be acceptable but it drives me nuts. :o) > For the die hard test-first folks, the "why" is recorded in > executable code in the form of new tests that explicitly > demonstrate why the changes had to be made to the production > code -- see for example, the rather heavy-weight Aegis version > control software <http://aegis.sourceforge.net>, which actually > requires you to check in news tests with any source modifications! > >> - When modifying a routine, remember to add a one-line entry with change >> date, programmer, and brief description. This one-line entry goes in >> the program history log of the documentation block. > > > Covered by the above, and don't be tempted to put a RCS/CVS tag > like $Log$ in each file -- it creates a mess of meta data that is > better managed by the version control software system. A lot of my code has the modification history tacked on the end - I tell myself it's for those folks who don't use CVS, but in reality it's a variation of the "Grandma's Cooking Secret" story (you know, wife cuts ends off of meatloaf, etc etc). I'm changing that though. > >> - Ensure input/output argument documentation in doc block is consistent >> with additions/deletions from calling list > > A lot of this can be obviated by using self-descriptive names, viz, > > http://c2.com/cgi/wiki?SystemOfNames > >> think the above requirements are a bit much - especially once we get >> everyone using CVS (or Subversion) > > > Agreed. Note: we've just switched from CVS to SVN primarily to be > able to move files (and directories) without having to do a special > jig to preserve it's revision history. I wanted to start everyone off fresh with svn here (they're nearly all source control virgins), but the svn client only comes bundled with RHE4.0 and most folks here have RHE3.0 (or windows) - the upshot being that the client has to be installed on their machines and that isn;t done as needed anymore so their OS has to be upgraded and it takes time to approve new upgrades and by then we're waiting for the next one and then.... blah blah blah. You get the idea. > FWIW, I have a canned talk on this whole team scientific software thing > based on NASA TM 2003-212421: > > http://techreports.larc.nasa.gov/ltrs/PDF/2003/tm/NASA-2003-tm212421.pdf > > that I've been asked to give at various places like U of Michigan > (CSEM), MIT (ACDL), U of Illinois (CSAR), U of Tennessee (SimCenter), > etc., if you are interested. I'll float that with the powers that be here and see if I can convince to get you up here. Thanks, paulv -- Paul van Delst CIMSS @ NOAA/NCEP/EMC
From: Pierre Asselin on 15 Mar 2006 09:08 Paul Van Delst <Paul.vanDelst(a)noaa.gov> wrote: > Pierre Asselin wrote: > > 2) Just make sure the [coding] standards are not harmful. > > I think *mandating* USE at module level would be harmful. > Excellent points all -- although I'm not sure I fully understand > what you meant by #2. What do you mean by "mandating USE at module > level"? The original question in this thread. When module procedures rely upon lower-level modules, do the coding standards require that you put USE statements at module scope rather than repeating USE (or USE, ONLY) in every procedure. Apparently we convinced you that the answer is "no". -- pa at panix dot com
From: Paul Van Delst on 15 Mar 2006 10:12
Pierre Asselin wrote: > Paul Van Delst <Paul.vanDelst(a)noaa.gov> wrote: > >>Pierre Asselin wrote: > > >>> 2) Just make sure the [coding] standards are not harmful. >>> I think *mandating* USE at module level would be harmful. > > >>Excellent points all -- although I'm not sure I fully understand >>what you meant by #2. What do you mean by "mandating USE at module >>level"? > > > The original question in this thread. When module procedures rely > upon lower-level modules, do the coding standards require that you > put USE statements at module scope rather than repeating USE (or > USE, ONLY) in every procedure. Apparently we convinced you that > the answer is "no". Ah, o.k. I see. No, I haven't changed my original feelings about that. I find it much more helpful (in writing and reading code) to put the USE statement at the module level rather than in every procedure (with or without ONLY clauses). My code follows that guideline. Rarely have I seen code (here) that puts the USE only in procedures as needed. The most common usage of USE is to put them in both the module (all those required) and the procedure (only the ones required) -- again, with or without ONLY clauses. However, this thread has convinced me that ONLY clauses are a good idea. All I need is a tool that makes it easy to construct/modify them when code is changed. As to *mandating* USE at module level ... well, I'm not writing these guidelines to wield like a big stick when they're not followed to the letter, but I do think that -- if all the developers involved agree upon them at some final point -- deviations need to be qualified (and, as you stated in your post, waivers granted if the qualification is valid). All the above sounds terribly red-tape-y ... I loathe the word "waiver" :o) Mostly I want people to think more about why they're coding the way they do and be open to changing. It's happened to me over the last week (some aspects just a little bit, others almost 180deg change) after asking the original question, and over the last month after the discussion here regarding Python/Ruby use for unit testing - and I feel much freer for it. Really. (I'm actually amazed at how much I wasn't thinking about the process, but I'll chalk that up to being busy and too focused :o). cheers, paulv p.s. I received a reply from the main code boss here about how the USE, ONLY: lines for the updated legacy code were constructed - by hand! And, when other developers[*] modify the code and remove dependencies, they rarely update the ONLY clause. (Remember that Fortran95 is still an exotic beastie for the most part hereabouts). [*] developers == scientists (including me). -- Paul van Delst CIMSS @ NOAA/NCEP/EMC |