From 84d6735fa2916e0dc848da383aace13c6774535e Mon Sep 17 00:00:00 2001 From: James Cherry Date: Tue, 5 Mar 2024 21:10:52 -0700 Subject: [PATCH] CodingGuidelines Signed-off-by: James Cherry --- doc/CodingGuidelines.txt | 55 +++++++++++++--------------------------- 1 file changed, 17 insertions(+), 38 deletions(-) diff --git a/doc/CodingGuidelines.txt b/doc/CodingGuidelines.txt index 80ea0eee..1c6f8dce 100644 --- a/doc/CodingGuidelines.txt +++ b/doc/CodingGuidelines.txt @@ -2,25 +2,21 @@ Naming conventions directory - lowercase (directory) filename - corresponding class name without prefix (Filename) -class - capitalized (ClassName) -member function - lowercase/capitalized (memberFunction) -member variable - lowercase/underscore/trailing underscore (member_variable_) +class - upper camel case (ClassName) +member function - upper camel case (memberFunction) +member variable - snake case with trailing underscore (member_variable_) Trailing underscore prevents conflict with accessor member function name. -function - lowercase/capitalized (functionName) +function - lower camel case (functionName) comments - use capitalized sentences that end with periods C++ code files should use a .cc file extension C++ header files should use a .hh file extension -Use ifdef/define's to protect headers from being read more than once. -Name the define variable the same as the header in uppercase. -For example, for Clock.hh +Use pragmas to protect headers from being read more than once instead of +ifdef/define. - #ifndef STA_CLOCK_H - #define STA_CLOCK_H - ... - #endif + #pragma once In general it is better to for class variables to use pointers to objects of other classes rather than embedding the instance directly. @@ -35,22 +31,23 @@ where Directory is the capitalized name of the sub-directory. Place comments describing public functions and classes in header files rather than code files because a consumer is more likely to have access to the header and that is the first place they will look. -Comments for private functions can be in the source file. The return type of a function should be on the line before the -function name. Spaces should be added after commas in the argument -list. Split the function arguments to fit on one line. For example: +function name. Arguments should be on separate lines to make it easier +to remove or add them without having to reformat the lines as they +change length. return_type -function(type1 arg1, type2, arg2) +function(type1 arg1, + type2 arg2) { } Functions should be less than one screen long. Break long functions -up into smaller ones. Lines should be less than 80 characters long. +up into smaller ones. Lines should be less than 90 characters long. -Try to avoid assignments inside `if'-conditions. For example, don't -write this: +Avoid assignments inside `if'-conditions. For example, don't write +this: if ((foo = (char *) malloc (sizeof *foo)) == 0) fatal ("virtual memory exhausted"); @@ -102,8 +99,8 @@ Don't declare class variables as const. It means any downstream code that accesses the member cannot modify it, which is overly restrictive. -Never use [] to lookup a map value because it creates a key/null value -pair if the lookup fails. Use sta::Map::findKey instead. +Avoid using [] to lookup a map value because it creates a key/null value +pair if the lookup fails. Use map::find or sta::Map::findKey instead. Avoid nested classes/enums because SWIG has trouble with them. @@ -127,24 +124,6 @@ cmd unknown keyword option cmd unknown sdf pin not found -................................................................ - -if configure.ac changes - autoconf - -if Makefile.am changes - automake - -Adding a new source file - Add header and source to source_dir/Makefile.am - cd source_dir; make clean - -Adding a new source directory - Add to configure.ac STA_SUBDIRS, AC_CONFIG_FILES - bootstrap - configure - make - ................................................................ Swig notes