Re: Code as documentation

Agree on end should have complete name. Emacs editor can do this
automatically.

6) Inside a module, declare everything as private, and everything
public must be explicitly declared. In another word, everything
default to be private.

7) Less or no comments. Use meaningful variable name of subroutine
names whenever possible. Obsolete comments can become poison. Try to
make the code readable first.

8) Try to generate other documents from source code.
Post processor that can pull documents out from the source code.

Fruit does one example for "executable requirement". The requirements
are written as test method name, or one variable spec inside the test
method.
Then a spec script can pull all of those in-code-requirement-document
out, to compile a document.
The benefits are obvious: 1) don't need to maintain a separate
reqirement document, or test plan document. 2) deadly clear about
which requirement is done, and which is not.

Example: ( http://fortranxunit.wiki.sourceforge.net/Executable+Specification+by+Fruit
)

in code:

subroutine
test_**calculator_should_produce_4_when_2_and_2_are_inputs**
use calculator, only: add
integer:: result

call add (2,2,result)
call assertEquals (4, result)
end subroutine
test_calculator_should_produce_4_when_2_and_2_are_inputs

in report:

fruit/sample/test >rake spec
(in fruit/sample/test)

All executable specifications from tests:
calculator
--
-- calculator should produce 4 when 2 and 2 are inputs
-- calculation should produce 4.0 when 2.0 and 2.0
are
inputs
-- calculator should remember previous calculation results



Thanks
~Andrew Chen
.

Relevant Pages

  • Re: Why does python not have a mechanism for data hiding?
    ... define a new class member from completely outside the class ... that cannot be declared private. ... would need to use a "mangled" name to access private data or methods. ... without source code? ...
    (comp.lang.python)
  • Re: Use of delegate
    ... the source code, we did not provide support for a third party dll without ... I create a string with 200 as we declare in the vb.net, ... Private Sub Button1_Click(ByVal sender As System.Object, ... Microsoft Online Partner Support ...
    (microsoft.public.dotnet.languages.vb)
  • Re: module pattern provides no privacy in Firefox
    ... ECMAScript has the ability to encapsulate data as "private" ... var obj = { ... is transmitted to the client as source code and interpreted/compiled ... guarantee that anything could be placed out of reach by a javascript ...
    (comp.lang.javascript)
  • URGENT Help With Scientific Calculator!
    ... I designed a calculator, and I need help with the rest of ... private JLabel output, blank; ... container.add(cos); ...
    (comp.lang.java.gui)
  • URGENT Help With Scientific Calculator!
    ... I designed a calculator, and I need help with the rest of ... private JLabel output, blank; ... container.add(cos); ...
    (comp.lang.java.developer)