Writing Good Code - Revision history

BernardoDalSeno: /* Matlab */

2009-09-14T16:26:37Z

‎Matlab

BernardoDalSeno: /* Header files */

2009-09-07T16:52:34Z

‎Header files

BernardoDalSeno: /* Comments */

2009-08-16T11:58:13Z

‎Comments

BernardoDalSeno: /* General */

2009-07-02T10:20:45Z

‎General

BernardoDalSeno: /* C and C++ code */

2009-06-16T15:55:16Z

‎C and C++ code

BernardoDalSeno: /* C and C++ code */

2009-06-16T15:55:01Z

‎C and C++ code

BernardoDalSeno: /* C and C++ code */

2009-04-27T17:11:27Z

‎C and C++ code

BernardoDalSeno: /* Header files */

2009-04-27T16:46:44Z

‎Header files

BernardoDalSeno: /* C and C++ code */

2009-04-27T16:44:25Z

‎C and C++ code

BernardoDalSeno: /* Names */

2009-04-22T11:44:44Z

‎Names

← Older revision		Revision as of 16:26, 14 September 2009
Line 135:		Line 135:

	Remember not to trust <code>mlint</code> too much; there is no perfect static analyzer (you remember [http://en.wikipedia.org/wiki/Rice%27s_theorem Rice's theorem], right?). If you have no warnings, it doesn't mean that your program is perfect.		Remember not to trust <code>mlint</code> too much; there is no perfect static analyzer (you remember [http://en.wikipedia.org/wiki/Rice%27s_theorem Rice's theorem], right?). If you have no warnings, it doesn't mean that your program is perfect.
		+
		+	===Comments===
		+
		+	Matlab has its own way to comment M-files, as comments are used to provide information for the <code>help</code> command, and also the command <code>lookfor</code> searches inside the first line of an M-file comment. See the section [http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_prog/f7-41453.html#f7-38702 Providing Help for Your Program] inside the topic [http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_prog/f7-41453.html Working with M-Files] and the topic [http://www.mathworks.com/access/helpdesk/help/techdoc/matlab_env/bruby4n-1.html#brubzjb-1 Providing Your Own Help and Demos] in the online Matlab documentation.

@@ Line 101: / Line 101: @@
 ===Header files===
-Apparently, header (include) files can be problematic, probably because of the Java background common to many people nowadays.  If you any doubt about them, Wikipedia does a good job in briefly explaining what [http://en.wikipedia.org/wiki/Header_file header files] are.
+Apparently, header (include) files can be problematic, probably because of the Java background common to many people nowadays.  If you have any doubt about them, Wikipedia does a good job in briefly explaining what [http://en.wikipedia.org/wiki/Header_file header files] are.
 Major misconceptions regards what goes inside a header file. This a topic better described in a programming manual (and you've already read it, haven't you?), but a good rule of thumb is: only declarations and definitions that neither reserve memory nor produce code.

@@ Line 47: / Line 47: @@
   ...
-So, what to comment? Good places for comments are class declarations, functions or methods (you tell what the function is about, what the parameters are, and describe the expected results and side effects), class attribute declarations, global or important variables, the beginning of a file, and a few others.  Also, when you take a tricky decision, please document it!
+So, what to comment? Good places for comments are:
 ===Debugging===

@@ Line 5: / Line 5: @@
 ==General==
-The source of the program is not only a way to obtain a binary that your computer can run, it is a way to express ideas.  They should be clear to the compiler, so it compiles and you have your nice executable, but they should be clear also to anyone that reads your code, including your fellow students, your supervisor, and, of course, you — even after a couple of months.  '''Write for your fellows, not only for the computer!'''
+The source of the program is not only a way to obtain a binary that your computer can run, it is a way to express ideas.  They should be clear to the compiler, so it compiles and you have your nice executable, but they should be clear also to anyone that reads your code, including your fellow students, your supervisor, and, of course, '''you''' — even after a couple of months.  Writing a program is the ultimate way to check your ideas and hypothesis.  So, '''write for you and your fellows, not only for the computer!'''
 ===I Think Therefore I Program===

@@ Line 86: / Line 86: @@
 In C++, never use the C-style cast operator, particularly with pointers.  Use <code>static_cast</code> or a constructor for classes, and <code>dynamic_cast</code> for pointers.  C-style casts are ambiguous, as they can mean many different type of casts, some of which are dangerous.  The only situation where a C-style cast may have a place is for conversion between built-in numeric types.
 ===Header files===
 Apparently, header (include) files can be problematic, probably because of the Java background common to many people nowadays.  If you any doubt about them, Wikipedia does a good job in briefly explaining what [http://en.wikipedia.org/wiki/Header_file header files] are.

← Older revision		Revision as of 17:11, 27 April 2009
Line 82:		Line 82:

	C (and C++) have a fair number of operators, with strictly defined precedences. Even if you know all the precedence rules by heart, don't assume others do; so, please use parentheses when writing complex expressions.		C (and C++) have a fair number of operators, with strictly defined precedences. Even if you know all the precedence rules by heart, don't assume others do; so, please use parentheses when writing complex expressions.
		+
		+	If you are writing any non-trivial project (anything that spans more than one file of source code can be considered non-trivial), you may want to use [http://www.stack.nl/~dimitri/doxygen/ Doxygen] for documentation. It's simple to use, and after you've learned how it works, it doesn't require additional work. On the contrary, it helps you in keeping your code well documented.

	===Header files===		===Header files===

← Older revision		Revision as of 16:46, 27 April 2009
Line 87:		Line 87:

	Major misconceptions regards what goes inside a header file. This a topic better described in a programming manual (and you've already read it, haven't you?), but a good rule of thumb is: only declarations and definitions that neither reserve memory nor produce code.		Major misconceptions regards what goes inside a header file. This a topic better described in a programming manual (and you've already read it, haven't you?), but a good rule of thumb is: only declarations and definitions that neither reserve memory nor produce code.
		+
		+	A header file should contain all (and only) the include directives necessary for its compilation, i.e., if the file makes use of any data type or symbol, it must include the header that defines such data type or symbol.

	There can be problems with header files, due to multiple or recursive inclusions. To avoid them, you can wrap their content in a <code>#ifndef</code>...<code>#endif</code> construct (inside the header file!), like this:		There can be problems with header files, due to multiple or recursive inclusions. To avoid them, you can wrap their content in a <code>#ifndef</code>...<code>#endif</code> construct (inside the header file!), like this:

@@ Line 81: / Line 81: @@
 The [http://www.google.com/search?q=%22Linux+kernel+coding+style%22 Linux kernel coding style] is an interesting reading, particularly chapters 3 (Placing Braces and Spaces), 4 (Naming), 6 (Functions), 8 (Commenting), 12 (Macros).
-For header (include) files, avoid problems from multiple or ricursive inclusions.  Wrap their content in a <code>#ifndef</code>...<code>#endif</code> construct (inside the header file!), like this:
+C (and C++) have a fair number of operators, with strictly defined precedences.  Even if you know all the precedence rules by heart, don't assume others do; so, please use parentheses when writing complex expressions.
   #ifndef MY_PROJECT_MY_HEADER_H
   #define MY_PROJECT_MY_HEADER_H
@@ Line 87: / Line 94: @@
   ...
   #endif
-The name of the macro should be something that is unlikely to clash with other macros; e.g., prepend the name of the your project.
+The name of the macro should be something that is unlikely to clash with other macros; e.g., prepend the name of your project.
-−
-C (and C++) have a fair number of operators, with strictly defined precedences.  Even if you know all the precedence rules by heart, don't assume others do; so, please use parentheses when writing complex expressions.
 ==Matlab==

@@ Line 13: / Line 13: @@
 ===Names===
-Names should be meaningful, short (at least, not too long), and to the point.  That applies to classes, variable, functions, module.  If the project you are working on or the language you are using come with a naming convention just follow it.  Names with wider scope (classes, public methods, global variables, global functions...) require more care.  They cannot be to simple to avoid clashing with local names, and both the meaning and the context should be clear.  'tmp' can be a good name for a local variable with a life of a couple of lines of code, or 'k' is good for loop counter, but they are really bad names for anything with a scope wider than a loop or a function.  If you have to store the name of a temporary file where you save the result of the application of a fast Fourier transform, something like 'fft_file_name' is more appropriate; if you have a counter that keeps track of the number of time you called the 'evaluate_fitness()' method (e.g., for statistical purposes), you could chose something like 'fitness_call_count'.
+Names should be meaningful, clear, short (at least, not too long), and to the point.  That applies to pretty everything: classes, variables, functions, modules, members.  Remember: the compiler doesn't care about names, but humans do; your colleagues are humans, and probably they want to understand your code when they happen to read it.  If the project you are working on or the language you are using come with a naming convention just follow it; separate words in names by using underscores '_' or mixedCaseLikeThis.
 ===Comments===