Re: Commenting the source code.

From: Herbert Rosenau (os2guy_at_pc-rosenau.de)
Date: 10/22/04 

Date: Fri, 22 Oct 2004 17:33:09 +0000 (UTC)

On Fri, 22 Oct 2004 10:23:28 UTC, "Profetas" <xuxu_18@yahoo.com>
wrote:

>
> Hi,
>
> I know that this is off topic. but I didn't know
> where to post.
>
> Do you comment your source code while coding or after coding.
>
> for example:
>
> you write a procedure and after it is working, you'll comment it.
>
> or
>
> you write a line of code and a comment following.

I follow these rules:
- design the whole program
- break down the design to be more specific
- break down each specific design to be more specific
  repeat until each problem is broken into peaces lttle enough
  to fill only a screen or a bit more
  build modules holding a sub problem (of a sub problem....)
  check anything. Recheck it again to be sure to have no mistake in
the design
- design the interfaces
  even no coding - only design
  recheck that them match any request, change if needed
- document anything well

- start filling modules with documented interfaces and empty function
definitions.
  let any trunc return one error result (NULL pointer when it has to
return a pinter in result, anything else that presents an error in
other cases)
  insert an debug functiion that says that the function is not
realised yet
  This gives you the possibility to start
- build the headers and document them
- build the makefile and document it
  test the makefile
- write, document, compile and debug debug fuctions.
  You needs debugged debug functions to get your debug sessions more
  successfully. Whereas successfull means dedect bugs, checks the
  wanted results occure.

Now the project can change in its coding phase
- code, low level fuctions
- comment anything logically
  that means write comments relayed to the logical funtionality
  but NOT to the coding
- check the comment as if it were code for correctness in logic and
flow
  correct errors now!
- when the comments are perfect fill each comment (section)
  with the matching code. Use the makefile to to test for errors in
  typing.
- write short testcase to debug each function. Neends no great
comments as they
  are used only temporary to test the fuctions for korrectness
  This ends up with well tested very, very low level fuctions. You
knows
  that each function does anything as espected - including failture
handling.
- restart at top of this section but one logical level higher
  while testing you can use the lower level functions without testing
them
  because the prior cycle has done that careful, so bugs are only in
the new code.

Comments are essential for
- finding design bugs before the first code line gets written
- finding bugs while coding (that is why your comment is on logical,
not
  coding level anyway
- finding bugs while debugging. Each programmer gets sometimes a bit
crazy
  and writes code other than the design says you should.

True, yes, designing of the whole program and all its lower leveled
functions costs a lot of time. But at least spending one day for the
design and checking it saves you a full week and more on coding and a
month on debugging. So spend any time you needs to get your design
perfect. You saves a multiple time of that in coding.

Debug each little fuction extensive. It is your time you wins. Test
each function separately before you goes to the next one. That is
because you can use it later without doubt of an bug inside it. So you
gets higher level functions more quick ready for use. 

-- 
Tschau/Bye
Herbert
Visit http://www.ecomstation.de the home of german eComStation

Relevant Pages

  • Re: Books / Articles on Embedded SW Architecture
    ... I deliver products, of any level of complexity, when they're bug-free. ... not crash" in mind) takes less time, mainly because it cuts out the whole asymptotic "reducing bugs to nearly but not quite zero - until we run out of time" phase. ... printing debug lines to stdout etc all have their usefulness and should be designed in from the ground up. ... Acceptance of failure is far too common in s/w design, and simply unacceptable in embedded work. ...
    (comp.arch.embedded)
  • Re: does VS C++ 2005 actually work????
    ... Anything that deals with teh actual IDE and is broken is ... probably due to either design flaws or bugs (testing apparently wasn't high on the list of ... Microsoft or have anything to do with the design of this product. ... I'm just trying debug the application using ...
    (microsoft.public.vc.mfc)
  • Re: OT - Productivity level?
    ... But I do design things, and I don't start coding until I ... has been tested, there were around 200 bugs or should I say 2E2 bugs, mostly ... I dont think there is any corelation between productivity and LOC. ...
    (microsoft.public.vc.mfc)
  • Re: Is top-down design feasible for a coffee-break roguelike?
    ... fundamental design decisions should be settled before doing coding.. ... is strongly linked to the game mechanics itself. ... but simply because it assumes diagonal movement is disallowed. ...
    (rec.games.roguelike.development)
  • Re: truly-optimized coding styles & design patterns in C#?
    ... grokking design patterns but try to find practical examples of each pattern ... apps you've written and seek out the simplest and most elegant ways to ... creating a small utility app vs coding something that has to fit into ... > exceptions classes, none of that. ...
    (microsoft.public.dotnet.languages.csharp)