File: CodingGuidelines.txt

package info (click to toggle)
opensta 0~20191111gitc018cb2+dfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 5,116 kB
  • sloc: cpp: 99,117; tcl: 8,530; yacc: 1,435; lex: 894; makefile: 541; sh: 107
file content (156 lines) | stat: -rw-r--r-- 4,399 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
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_)
                  Trailing underscore prevents conflict with accessor 
                  member function name.
function - lowercase/capitalized (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

  #ifndef STA_CLOCK_H
  #define STA_CLOCK_H
  ...
  #endif

In general it is better to for class variables to use pointers to
objects of other classes rather than embedding the instance directly.
This only requires that the class be declared rather than defined,
many times breaking a dependency on another header file. 

Header files that define the classes of a sub-directory allow other
headers to have pointers to the objects without pulling in the details
of the class definitions.  These headers are named "DirectoryClass.hh"
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:

return_type 
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.

Try to avoid assignments inside `if'-conditions.  For example, don't
write this:

     if ((foo = (char *) malloc (sizeof *foo)) == 0)
       fatal ("virtual memory exhausted");

instead, write this:

     foo = (char *) malloc (sizeof *foo);
     if (foo == 0)
       fatal ("virtual memory exhausted");


Use braces around if/for bodies that are more than one line.
IE, 
  if (pred)
    for (int i = 0; i < len; i++) {  // this body should be in {}'s
       ...
    }

Add a default clause to all switches calling switchCaseNotHandled:

  switch (type) {
  case edge_interconnect:
    ...
  default:
    switchCaseNotHandled();
  }

Put return types for functions on the line before the function name:

 Cell *
 Library::findCell(char *name)
 {
  ...
 }

Class member functions should be grouped in public, protected and then
private order.

 class Frob
 {
 public:
 protected:
 private:

 friend class Frobulator;
 }

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 nested classes/enums because SWIG has trouble with them.

................................................................
Warning
get_<object> not found
sdf timing arc not found
disabling timing arcs to break loops
virtual clock with no sources (no pins)
invalid endpoint for constrained paths
sdf DESIGN does not match top level cell name
set_input_delay on clk port (deprecation warning)
link cannot resolve reference (module/cell not found)

Errors
cannot open file
file syntax error
cmd illegal command option combinations
cmd extra positional args
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

C null pointers (zero) turn into "NULL" values in TCL.

TCL "NULL" strings turn into NULL (zero) pointers in C.

# TCL lexpr-funcall
eval exec $prog $args