fivedev/harbour-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

* doc/codestyl.txt

Browse Source 
* Added Documentation item

  + doc/es/codestyl.txt
    + Documented code style
This commit is contained in:
Alejandro de Garate
2004-05-25 03:08:16 +00:00
parent 9e6071a60b
commit dd4936a618
1 changed files with 38 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
harbour/doc/codestyl.txt
View File

@@ -161,6 +161,44 @@ Syntax and indentation
consistency in indenture so that definitions, comments, and
control structures line up correctly.
Documentation
--------------
[1] Whenever be possible document yourself functions you developed.
Usually is hard to understand code wrotted by other person, moreover
when it involve some obscure algorithm, system's vars or attributes
or data unavailable for the documentator.
This is particularly evident for low level functions.
[2] After some time function was wrotted, work become more difficult because
it's need it to read the code several times (even for the own developer).
This is evident when variables don't have useful names (and uses only
letters).
Because that, please DO NOT leave functions without documentation.
[3] If function made calls to other non-documented functions, and the
original developer are not available anymore, could be so hard and even
impossible to document it.
[4] Tracking which functions are documented and which are not, and if they
are total or partially documented are a waste of resources in time and
people.
[5] If you are the developer of the function don't worry by your narrative
skills, concentrate in what functions do, which arguments it gets,
which are its purpose and specially what information function returns.
[6] If you are the developer of the function, and you are using system's
functions or vars undocumented, please explain it as much as possible.
If you use a obscure or strange algorithm (i.e md5 ) please explain what
it does and how it works.
[7] Notes, remarks and explainings enclose always between the /* */ pair,
please don't use the double bar // because it difficults portability.
[8] Remember... documentation it's a much time consuming work, usually
takes more time writing the documentation of a function that writing
the function itself.