Coding style - Revision history

Jpye at 07:01, 23 February 2011

2011-02-23T07:01:32Z

← Older revision		Revision as of 07:01, 23 February 2011
Line 159:		Line 159:

	For memory allocation in the C code, please use the macros ASC_NEW, ASC_NEW_ARRAY, ASC_NEW_CLEAR, ASC_NEW_ARRAY_CLEAR and ASC_FREE, defined in <ascend/utilities/ascMalloc.h>. Prefer these over alternatives like ascfree, ascmalloc and malloc. Using these macros universally will make use of various memory debugging tools a bit easier.		For memory allocation in the C code, please use the macros ASC_NEW, ASC_NEW_ARRAY, ASC_NEW_CLEAR, ASC_NEW_ARRAY_CLEAR and ASC_FREE, defined in <ascend/utilities/ascMalloc.h>. Prefer these over alternatives like ascfree, ascmalloc and malloc. Using these macros universally will make use of various memory debugging tools a bit easier.

			== Filenames ==

			Filenames in ASCEND should be all in lower-case. This ensures minimal problems between Windows (which is not case-sensitive) and Linux (which '''is''' case-sensitive).

	[[Category:Development]]		[[Category:Development]]

Jpye: /* Doxygen */

2011-02-21T04:37:53Z

Doxygen

← Older revision		Revision as of 04:37, 21 February 2011
Line 132:		Line 132:
	== Doxygen ==		== Doxygen ==

	All API-exposed C functions should be provided with commenting that can be used by [http://www.doxygen.org Doxygen]. We use this program to generate [our API documentation. There are plenty of good examples of how this is done, see the various header files in base/generic/system, for example.		All API-exposed C functions should be provided with commenting that can be used by [http://www.doxygen.org Doxygen]. We use this program to generate [{{doxyhome}} our API documentation]. There are plenty of good examples of how this is done, see the various header files in base/generic/system, for example.

	== Python code ==		== Python code ==

Jpye at 04:37, 21 February 2011

2011-02-21T04:37:33Z

← Older revision		Revision as of 04:37, 21 February 2011
Line 1:		Line 1:
	ASCEND has had a large number of contributors over its [[ASCEND_history\|history]] with the result that several different code styles are present in the core code and in the various GUI and solver code, etc. We are going to try to establish a few style guidelines here; if everyone can try to stick to these for new code in ASCEND then it will allow us to converge gradually to more uniformly readable code. ~~In the mean time~~, '''~~there is~~ to ~~be no~~ 'repair' of existing code to meet the current guidelines; such repairs make it much more difficult to correctly merge code from developers working in parallel~~'''~~.		ASCEND has had a large number of contributors over its [[ASCEND_history\|history]] with the result that several different code styles are present in the core code and in the various GUI and solver code, etc. We are going to try to establish a few style guidelines here; if everyone can try to stick to these for new code in ASCEND then it will allow us to converge gradually to more uniformly readable code.

			Unless you are permitted to work on our main 'trunk' line of code, please '''do not''' attempt to 'repair' existing code to meet the current guidelines; such repairs make it much more difficult to correctly merge code from developers working in parallel.

	== GPL headers ==		== GPL headers ==
Line 112:		Line 114:
	* C code should use /* this style */ of comments for all developer comments.		* C code should use /* this style */ of comments for all developer comments.
	* It is '''NOT''' acceptable to use "//" comments in C code to comment-out temporary #defines and so on; c89 does not allow compilation of these comments and we will continue to support c89 for a very long time.		* It is '''NOT''' acceptable to use "//" comments in C code to comment-out temporary #defines and so on; c89 does not allow compilation of these comments and we will continue to support c89 for a very long time.
	* Intermediate lines of comments should not not be started with a "*", ie		* Intermediate lines of comments should not not be started with a "*", i.e.
	<source lang="c">/* multi-line comment:		<source lang="c">/* multi-line comment:
	* this kind is WRONG		* this kind is WRONG
Line 124:		Line 126:
	* Conservation rule: in many places (particularly the solvers), older styles are in use with multiple kinds of comment line prefix within the comment block. Reformatting these comments destroys information and should not be done.		* Conservation rule: in many places (particularly the solvers), older styles are in use with multiple kinds of comment line prefix within the comment block. Reformatting these comments destroys information and should not be done.

	== ~~Doxygen~~ ==		== API functions ==

	~~All API-exposed C functions~~ should be ~~provided with commenting that can be used~~ by ~~[http:~~/~~/www.doxygen.org Doxygen]. We use this program~~ to ~~generate our API documentation~~. ~~There~~ are ~~plenty of good examples of how~~ this is ~~done, see the various header files in base/generic/system, for example~~.		Functions in libascend which will be accessed by 'user' code (GUI code, test suite code, etc) outside libascend should be prefixed in the relevant .h header file by <tt>ASC_DLLSPEC</tt>, which ensures that the relevant symbols are correctly exported to the shared library symbol list. This may not be necessary on your development system, but there are at least some systems where this is essential.

			== Doxygen ==

			All API-exposed C functions should be provided with commenting that can be used by [http://www.doxygen.org Doxygen]. We use this program to generate [our API documentation. There are plenty of good examples of how this is done, see the various header files in base/generic/system, for example.

	== Python code ==		== Python code ==
Line 135:		Line 139:

	Currently, no automated documentation generators are being used with our Python code but we hope to change that soon. We will adopt conventions similar to those used by Gaphas.		Currently, no automated documentation generators are being used with our Python code but we hope to change that soon. We will adopt conventions similar to those used by Gaphas.


	== C++ code ==		== C++ code ==

	There is a moderate amount of C++ code in ASCEND as part of the Python API. This code helped to make the API easier to write, because of the ability to easily wrap STL data types using SWIG. We would ultimately like to clean out this C++ code, because it is bulky and slow to compile, and less efficient. Please consider this fact before plunging in to a lot of C++ coding. We would really like ASCEND to be pure C plus Python if possible.		There is a moderate amount of C++ code in ASCEND as part of the Python API. This code helped to make the API easier to write, because of the ability to easily wrap STL data types using SWIG. We would ultimately like to clean out this C++ code, because it is bulky and slow to compile, and less efficient. Please consider this fact before plunging in to a lot of C++ coding. We would really like ASCEND to be pure C plus Python if possible.


	== Tcl/Tk code ==		== Tcl/Tk code ==

	The older (but still more mature and complete) GUI for ASCEND is written with a C-to-Tcl interface layer together with Tcl/Tk GUI code. We are not actively developing the Tcl/Tk GUI; if you see features in that GUI that are missing from the PyGTK you are encouraged to make a note of that and think about how such features could be migrated.		The older (but still more mature and complete) GUI for ASCEND is written with a C-to-Tcl interface layer together with Tcl/Tk GUI code. We are not actively developing the Tcl/Tk GUI; if you see features in that GUI that are missing from the PyGTK you are encouraged to make a note of that and think about how such features could be migrated.


	== Compiler warnings ==		== Compiler warnings ==

	When building C and C++ code, please make sure that you are seeing '-Wall' flags (for GCC), to ensure that you're being warned about all possible faux pas that you may be making.		When building C and C++ code, please make sure that you are seeing '-Wall' flags (for GCC), to ensure that you're being warned about all possible faux pas that you may be making.


	== Assertions ==		== Assertions ==

	For assertions in the C code, please use the assertion macros/functions defined in the header file <ascend/compiler/ascPanic.h>. Avoid making direct use of <assert.h> from the C Standard Library.		For assertions in the C code, please use the assertion macros/functions defined in the header file <ascend/compiler/ascPanic.h>. Avoid making direct use of <assert.h> from the C Standard Library.



	== Memory allocation ==		== Memory allocation ==
Line 162:		Line 160:
	For memory allocation in the C code, please use the macros ASC_NEW, ASC_NEW_ARRAY, ASC_NEW_CLEAR, ASC_NEW_ARRAY_CLEAR and ASC_FREE, defined in <ascend/utilities/ascMalloc.h>. Prefer these over alternatives like ascfree, ascmalloc and malloc. Using these macros universally will make use of various memory debugging tools a bit easier.		For memory allocation in the C code, please use the macros ASC_NEW, ASC_NEW_ARRAY, ASC_NEW_CLEAR, ASC_NEW_ARRAY_CLEAR and ASC_FREE, defined in <ascend/utilities/ascMalloc.h>. Prefer these over alternatives like ascfree, ascmalloc and malloc. Using these macros universally will make use of various memory debugging tools a bit easier.

			[[Category:Development]]


	[[Category:Development]]

Jpye: /* Global variables */

2011-01-24T07:05:54Z

Global variables

← Older revision		Revision as of 07:05, 24 January 2011
Line 106:		Line 106:
	== Global variables ==		== Global variables ==

	Please, avoid the use of global variables at all times. We don't want any new global variables appearing; we're currently working to remove those that are there at present.		Please, avoid the use of global variables at all times. We don't want any new global variables appearing; we're currently working to remove [[Global variables\|those that are there at present]].


	== Comments in C/C++ code ==		== Comments in C/C++ code ==

Jpye: /* Tabs */

2011-01-24T07:03:51Z

Tabs

← Older revision		Revision as of 07:03, 24 January 2011
Line 54:		Line 54:
	* Do not use tabs to align comments after lists of variables etc; these break when people view the code with a different tab width.		* Do not use tabs to align comments after lists of variables etc; these break when people view the code with a different tab width.
	* It is a good practice to add "mode lines" at the start or end of files so that editors like [http://vimdoc.sourceforge.net/htmldoc/options.html#modeline vim], [http://www.delorie.com/gnu/docs/emacs/emacs_486.html emacs], [http://library.gnome.org/users/gedit/2.29/gedit-modelines-plugin.html.en gedit] and [http://kate-editor.org/2006/02/09/kate-modelines/ kate] and others can automatically set the tab settings when code is loaded for editing, even if the coder's defaults are different.		* It is a good practice to add "mode lines" at the start or end of files so that editors like [http://vimdoc.sourceforge.net/htmldoc/options.html#modeline vim], [http://www.delorie.com/gnu/docs/emacs/emacs_486.html emacs], [http://library.gnome.org/users/gedit/2.29/gedit-modelines-plugin.html.en gedit] and [http://kate-editor.org/2006/02/09/kate-modelines/ kate] and others can automatically set the tab settings when code is loaded for editing, even if the coder's defaults are different.
	* Read this: [http://www.movementarian.org/docs/whytabs/]		* Read this for a justification of why we like tabs and not spaces: http://www.movementarian.org/docs/whytabs/

	== C code conventions ==		== C code conventions ==

Jpye: /* Tabs */

2011-01-24T07:03:16Z

Tabs

← Older revision		Revision as of 07:03, 24 January 2011
Line 53:		Line 53:
	* The only place that tabs should be present in your code is as part of the whitespace at the start of a line.		* The only place that tabs should be present in your code is as part of the whitespace at the start of a line.
	* Do not use tabs to align comments after lists of variables etc; these break when people view the code with a different tab width.		* Do not use tabs to align comments after lists of variables etc; these break when people view the code with a different tab width.
	* It is a good practice to a "mode lines" at the start or end of files so that editors like vim, emacs, gedit and others can automatically set the tab settings when code is loaded for editing, even if the coder's defaults are different.		* It is a good practice to add "mode lines" at the start or end of files so that editors like [http://vimdoc.sourceforge.net/htmldoc/options.html#modeline vim], [http://www.delorie.com/gnu/docs/emacs/emacs_486.html emacs], [http://library.gnome.org/users/gedit/2.29/gedit-modelines-plugin.html.en gedit] and [http://kate-editor.org/2006/02/09/kate-modelines/ kate] and others can automatically set the tab settings when code is loaded for editing, even if the coder's defaults are different.
	* Read this: [http://www.movementarian.org/docs/whytabs/]		* Read this: [http://www.movementarian.org/docs/whytabs/]

Jpye at 07:00, 24 January 2011

2011-01-24T07:00:52Z

← Older revision		Revision as of 07:00, 24 January 2011
Line 1:		Line 1:
	ASCEND has had a large number of contributors over its [[ASCEND_history\|history]] with the result that several different code styles are present in the core code and in the various GUI and solver code, etc. We are going to try to establish a few style guidelines here; if everyone can try to stick to these for new code in ASCEND then it will allow us to converge gradually to more uniformly readable code. In the mean time, '''there is to be no 'repair' of existing code to meet the current guidelines; such repairs ~~diminish the ability~~ to merge ~~correctly~~ code from developers working in parallel'''.		ASCEND has had a large number of contributors over its [[ASCEND_history\|history]] with the result that several different code styles are present in the core code and in the various GUI and solver code, etc. We are going to try to establish a few style guidelines here; if everyone can try to stick to these for new code in ASCEND then it will allow us to converge gradually to more uniformly readable code. In the mean time, '''there is to be no 'repair' of existing code to meet the current guidelines; such repairs make it much more difficult to correctly merge code from developers working in parallel'''.

	== GPL headers ==		== GPL headers ==

Jpye at 07:00, 24 January 2011

2011-01-24T07:00:09Z

← Older revision		Revision as of 07:00, 24 January 2011
Line 1:		Line 1:
	ASCEND has had a large number of contributors over its [[ASCEND_history\|history]] with the result that several different code styles are present in the core code and in the various GUI and solver code, etc. We are going to try to establish a few style guidelines here; if everyone can try to stick to these for new code in ASCEND then it will allow us to converge gradually to more uniformly readable code. In the mean time, '''there is to be no 'repair' of existing code to meet the current guidelines; such repairs ~~destroy~~ the ability to merge correctly code from developers working in parallel'''.		ASCEND has had a large number of contributors over its [[ASCEND_history\|history]] with the result that several different code styles are present in the core code and in the various GUI and solver code, etc. We are going to try to establish a few style guidelines here; if everyone can try to stick to these for new code in ASCEND then it will allow us to converge gradually to more uniformly readable code. In the mean time, '''there is to be no 'repair' of existing code to meet the current guidelines; such repairs diminish the ability to merge correctly code from developers working in parallel'''.

	== GPL headers ==		== GPL headers ==

Jpye: /* GPL headers */

2011-01-24T06:57:50Z

GPL headers

← Older revision		Revision as of 06:57, 24 January 2011
Line 4:		Line 4:
	All code files should begin with a "GPL block" -- the format for C code is shown below. Copyright should by preference be assigned to Carnegie Mellon University, because that improves the chances of successfully fighting a license offender. Note that if you're not willing to place a GPL license at the top of code you are contributing to ASCEND, then we need to talk to you before you make your contribution. Maintaining a suitable open source license for our code is very important to the project. Exception: LGPL is also acceptable if the code is fully separable from existing GPL code.		All code files should begin with a "GPL block" -- the format for C code is shown below. Copyright should by preference be assigned to Carnegie Mellon University, because that improves the chances of successfully fighting a license offender. Note that if you're not willing to place a GPL license at the top of code you are contributing to ASCEND, then we need to talk to you before you make your contribution. Maintaining a suitable open source license for our code is very important to the project. Exception: LGPL is also acceptable if the code is fully separable from existing GPL code.
	<source lang="c">/* ASCEND modelling environment		<source lang="c">/* ASCEND modelling environment
	Copyright (C) ~~2009~~ Carnegie Mellon University		Copyright (C) 2011 Carnegie Mellon University

	This program is free software; you can redistribute it and/or modify		This program is free software; you can redistribute it and/or modify
Line 40:		Line 40:

	/* now start with the real business... */</source>		/* now start with the real business... */</source>

	== Conserve existing code ==		== Conserve existing code ==

Jpye at 06:57, 24 January 2011

2011-01-24T06:57:24Z

← Older revision		Revision as of 06:57, 24 January 2011
Line 3:		Line 3:
	== GPL headers ==		== GPL headers ==
	All code files should begin with a "GPL block" -- the format for C code is shown below. Copyright should by preference be assigned to Carnegie Mellon University, because that improves the chances of successfully fighting a license offender. Note that if you're not willing to place a GPL license at the top of code you are contributing to ASCEND, then we need to talk to you before you make your contribution. Maintaining a suitable open source license for our code is very important to the project. Exception: LGPL is also acceptable if the code is fully separable from existing GPL code.		All code files should begin with a "GPL block" -- the format for C code is shown below. Copyright should by preference be assigned to Carnegie Mellon University, because that improves the chances of successfully fighting a license offender. Note that if you're not willing to place a GPL license at the top of code you are contributing to ASCEND, then we need to talk to you before you make your contribution. Maintaining a suitable open source license for our code is very important to the project. Exception: LGPL is also acceptable if the code is fully separable from existing GPL code.
	<source lang="~~a4c~~">/* ASCEND modelling environment		<source lang="c">/* ASCEND modelling environment
	Copyright (C) 2009 Carnegie Mellon University		Copyright (C) 2009 Carnegie Mellon University