Re: Part 15
Posted: Sat Dec 22, 2018 1:14 am
#431 From: Cristiano Guadagnino <criguada@...>
Date: Thu Apr 25, 2002 6:11 pm
Subject: Coding guidelines and progress criguada
Offline Offline
Send Email Send Email
Invite to Yahoo! 360° Invite to Yahoo! 360°
Hi all,
recently there has been much rumour unrelated (or loosely related) to the
project.
This message is to let all know that developing is going on, the CVS is being
updated quite regularly, and the coding guidelines are in their more-or-less
final state.
You can get the current source using CVS:
SET CVSROOT=:pserver:osfree@...:d:/project
password: readonly
You won't be able to submit changes though. To have a read/write account, ask
(nicely ) to JMA.
If you aren't familiar with CVS, please take time to familiarize. I'm using CVS
1.11, and this is the preferred choice (with 1.10.6 being a good second).
I'm including the coding guidelines below, and I'll upload the file in the
files area on Yahoo, for future reference.
I'll upload also Astyle 1.15.3 (see the guidelines).
Here are the guidelines:
The osFree Project Coding Standards
Draft
+-----------------------------------------------------------------------------+
Doxygen 1.2.11 is available on Hobbes.
Astyle 1.13.0 is available on Hobbes.
(Astyle 1.15.3 is available on sourceforge, and it compiles without mods on
EMX v0.9d. It contains several fixes.)
+-----------------------------------------------------------------------------+
Choose a standard and stick to it. Code should be readable in the first
place. Readable code is preferable to religious adherence to a standard.
We are humans, not machines!
Use a tab indent of 4 chars and make sure to configure your editor
to save spaces instead of hard tabs. Hard tabs are evil because there is
no single standard.
Using Astyle on source code before submitting it to the repository is a
good idea (see below for the setup).
+-----------------------------------------------------------------------------+
We will use Doxygen to generate documentation but please don't create
excessive internal comments. Code that is easy to read will be easy to
maintain and is preferable to overly complex structure.
If you insert too many comments it will become difficult to follow the code.
These guidelines should be helpful:
- Extensive comments are good to describe a function purpose, its
parameters, etc, and should be inserted right before the function
_definition_ (i.e. in the source, not the header).
- Data types should instead be documented in the header files.
- Before function declaration you should insert a short comment
summarizing the purpose.
- Apart from the long winded comment before function definition,
keep your comments one or two lines long, either before the line
of code, or to the right of the line.
- We will be using CVS, hence there is no need to insert a marker for
changes. Anyone can see who changed a line (and why) using CVS tools.
- If you need to insert large pieces of documentation, remember that
Doxygen allows external links.
Please read the Doxygen manual, at least the introduction.
For Doxygen comments the following formats are recommended:
(long format)
/*!
...
*/
(short format)
//!
(short format for comments to the right of the code)
//!<
+-----------------------------------------------------------------------------+
Naming conventions for variables should match those used in IBM's OS/2
Toolkit and associated documentation. It is assumed that all prospective
osFree programmers are well acquainted with these conventions.
Note: it's not necessary that _every_ single variable be named according
to the convention. If you use a temporary variable for a short code
routine, there is no necessity to adhere to the convention. Typical
examples are counters, indexes used in loops. But keep in mind that
code should be readable, so don't use vast amounts of single-letter
variables. Again, using common sense is advisable.
If you use long, descriptive variable names, it might be a good idea to
separate words with underscores rather than using exotic capitalizations
to make them understandable.
+-----------------------------------------------------------------------------+
Regarding CVS, a good rule of thumb when writing the log messages is:
don't say _what_ you changed because anyone can easily see it through
a simple diff. Instead, say _why_ you changed something.
+-----------------------------------------------------------------------------+
In general: remember that other people will need to read (and perhaps
modify!) your code. Don't use an exotic or too "personal" coding style.
+-----------------------------------------------------------------------------+
Doxygen template configuration file:
PROJECT_NAME = "prjname"
OUTPUT_DIRECTORY = .
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INCLUDE_PATH = .
INPUT = .
FILE_PATTERNS = *.h *.c
QUIET = NO
TAB_SIZE = 4
GENERATE_TODOLIST = YES
GENERATE_BUGLIST = YES
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_STATIC = YES
JAVADOC_AUTOBRIEF = NO
Put this statements in a file, name it accordingly (e.g. tree.dxy for the
tree CLI utility) and copy it where the source files are. Then invoke
Doxygen like this:
doxygen prjname.dxy
and the documentation will be created in the "html" subdirectory.
+-----------------------------------------------------------------------------+
Astyle parameters:
mode=c
brackets=linux
indent=spaces=4
indent-switches
suffix=.org
min-conditional-indent=0
pad=oper
one-line=keep-statements
Put these parameters in a file named .astylerc, and copy this file in your
%HOME% directory.
Note that this setup is not completely satisfactory. While it produce a good
output, it doesn't support aligning of comment to the right of the code.
You may want to realign comments after Astyle's work.
+--------------------------------- END ---------------------------------------+
Date: Thu Apr 25, 2002 6:11 pm
Subject: Coding guidelines and progress criguada
Offline Offline
Send Email Send Email
Invite to Yahoo! 360° Invite to Yahoo! 360°
Hi all,
recently there has been much rumour unrelated (or loosely related) to the
project.
This message is to let all know that developing is going on, the CVS is being
updated quite regularly, and the coding guidelines are in their more-or-less
final state.
You can get the current source using CVS:
SET CVSROOT=:pserver:osfree@...:d:/project
password: readonly
You won't be able to submit changes though. To have a read/write account, ask
(nicely ) to JMA.
If you aren't familiar with CVS, please take time to familiarize. I'm using CVS
1.11, and this is the preferred choice (with 1.10.6 being a good second).
I'm including the coding guidelines below, and I'll upload the file in the
files area on Yahoo, for future reference.
I'll upload also Astyle 1.15.3 (see the guidelines).
Here are the guidelines:
The osFree Project Coding Standards
Draft
+-----------------------------------------------------------------------------+
Doxygen 1.2.11 is available on Hobbes.
Astyle 1.13.0 is available on Hobbes.
(Astyle 1.15.3 is available on sourceforge, and it compiles without mods on
EMX v0.9d. It contains several fixes.)
+-----------------------------------------------------------------------------+
Choose a standard and stick to it. Code should be readable in the first
place. Readable code is preferable to religious adherence to a standard.
We are humans, not machines!
Use a tab indent of 4 chars and make sure to configure your editor
to save spaces instead of hard tabs. Hard tabs are evil because there is
no single standard.
Using Astyle on source code before submitting it to the repository is a
good idea (see below for the setup).
+-----------------------------------------------------------------------------+
We will use Doxygen to generate documentation but please don't create
excessive internal comments. Code that is easy to read will be easy to
maintain and is preferable to overly complex structure.
If you insert too many comments it will become difficult to follow the code.
These guidelines should be helpful:
- Extensive comments are good to describe a function purpose, its
parameters, etc, and should be inserted right before the function
_definition_ (i.e. in the source, not the header).
- Data types should instead be documented in the header files.
- Before function declaration you should insert a short comment
summarizing the purpose.
- Apart from the long winded comment before function definition,
keep your comments one or two lines long, either before the line
of code, or to the right of the line.
- We will be using CVS, hence there is no need to insert a marker for
changes. Anyone can see who changed a line (and why) using CVS tools.
- If you need to insert large pieces of documentation, remember that
Doxygen allows external links.
Please read the Doxygen manual, at least the introduction.
For Doxygen comments the following formats are recommended:
(long format)
/*!
...
*/
(short format)
//!
(short format for comments to the right of the code)
//!<
+-----------------------------------------------------------------------------+
Naming conventions for variables should match those used in IBM's OS/2
Toolkit and associated documentation. It is assumed that all prospective
osFree programmers are well acquainted with these conventions.
Note: it's not necessary that _every_ single variable be named according
to the convention. If you use a temporary variable for a short code
routine, there is no necessity to adhere to the convention. Typical
examples are counters, indexes used in loops. But keep in mind that
code should be readable, so don't use vast amounts of single-letter
variables. Again, using common sense is advisable.
If you use long, descriptive variable names, it might be a good idea to
separate words with underscores rather than using exotic capitalizations
to make them understandable.
+-----------------------------------------------------------------------------+
Regarding CVS, a good rule of thumb when writing the log messages is:
don't say _what_ you changed because anyone can easily see it through
a simple diff. Instead, say _why_ you changed something.
+-----------------------------------------------------------------------------+
In general: remember that other people will need to read (and perhaps
modify!) your code. Don't use an exotic or too "personal" coding style.
+-----------------------------------------------------------------------------+
Doxygen template configuration file:
PROJECT_NAME = "prjname"
OUTPUT_DIRECTORY = .
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INCLUDE_PATH = .
INPUT = .
FILE_PATTERNS = *.h *.c
QUIET = NO
TAB_SIZE = 4
GENERATE_TODOLIST = YES
GENERATE_BUGLIST = YES
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_STATIC = YES
JAVADOC_AUTOBRIEF = NO
Put this statements in a file, name it accordingly (e.g. tree.dxy for the
tree CLI utility) and copy it where the source files are. Then invoke
Doxygen like this:
doxygen prjname.dxy
and the documentation will be created in the "html" subdirectory.
+-----------------------------------------------------------------------------+
Astyle parameters:
mode=c
brackets=linux
indent=spaces=4
indent-switches
suffix=.org
min-conditional-indent=0
pad=oper
one-line=keep-statements
Put these parameters in a file named .astylerc, and copy this file in your
%HOME% directory.
Note that this setup is not completely satisfactory. While it produce a good
output, it doesn't support aligning of comment to the right of the code.
You may want to realign comments after Astyle's work.
+--------------------------------- END ---------------------------------------+