 |
Mesh Oriented datABase
(version 5.5.1)
An array-based unstructured mesh library
|
|
Mesh Oriented datABase
(version 5.5.1)
An array-based unstructured mesh library
|
1 /*!
2 \page styleguide Coding Style Guide
3 Code developed in %MOAB should follow the coding styles described here. Any deviations from this style
4 guide will result in severe berating and other verbal abuse.
5
6 \section dirstructure MOAB Directory Structure
7 %MOAB source code is organized in the following directory structure: \n
8 - doc: Documentation is put here, along with the input file for Doxygen. Most %MOAB documentation is doxygen-processed.
9 - examples: Examples of %MOAB usage, both small and large. These programs are not meant to be used as unit tests, but
10 rather as further documentation on %MOAB usage.
11 - src : Mesh related source codes. It includes:
12 - io: %MOAB Input/Output classes.
13 - moab: %MOAB core classes.
14 - lotte: Computational Meshing basics.
15 - parallel: Parallel mesh computation, i/o data processing methods.
16 - test: All unit test programs should go below this directory.
17 Please put the unit tests into their related subdirectories based on the test's
18 purpose if possible.
19 If you're designing a new class or other code for %MOAB and are not sure where to put it, try to find something similar
20 and put it there. Otherwise, email the %MOAB email list for pointers. <em> In general, you should not need to create new
21 subdirectories in the %MOAB source code, except when implementing a new algorithm with more than about 2 files.</em>
22
23 \section sourcestyle Source Code Style and Best Practices
24 %MOAB code should abide by the following general rules:
25 - Names:
26 - Class names should be in the CamelBack style, e.g. EdgeMesh or VertexMesher.
27 - Class member variables should be camelBack, e.g. EdgeMesh::schemeType; each member variable, e.g. int memberVariable,
28 should have set/get functions void member_variable(int newval) and int member_variable(), respectively.
29 - Enumeration values should be all captitalized, with underscores avoided if possible (the enumeration name indicates
30 the general purpose of the enumeration, so e.g. we use EQUAL, not EQUAL_MESH)
31 - Source code should not contain tabs or MS-DOS newlines; tabs and other indentations should be set to a width of 2 spaces.
32 For general tips on how to set your editor for this, see the %MOAB-dev discussion starting with <a href="https://lists.mcs.anl.gov/mailman/private/moab-dev/2011/000519.html">this message</a>.
33 - Each class header should be fully commented; that includes:
34 - A \\file comment block at the top of the file; DO NOT include things like Author and Date blocks; this stuff is available
35 from subversion if we really need to know.
36 - A \\class comment block, formatted like those in the %MOAB core classes. THE FIELDS AFTER THE CLASS NAME ARE VERY IMPORTANT,
37 as they tell developers how to include the class declaration in their code. This information goes into the "Detailed
38 Description" portion of the class documentation. This block should include any features or limitations of the class.
39 Eventually, we'll impose some standard boilerplate that each meshing class should use.
40 Until then, please keep this block to around a paragraph.
41 - Each function in both the public and private interfaces should be commented, INCLUDING ANY ARGUMENTS AND RETURN VALUES.
42 See the %MOAB classes for examples of how to format these comments. As a rule of thumb, your code should run through
43 Doxygen without generating any warnings; in fact, Doxygen is sometimes helpful at pointing out inconsistencies in your
44 class declaration.
45 - Developers should avoid using \#include in header files, as they propagate dependencies more widely than necessary. The only
46 cases where other includes are needed are to import the declaration for a parent class, and to declare types used as
47 non-pointer and non-reference function arguments. In most cases, a forward-declaration statement (e.g. 'class MKCore')
48 will suffice.
49 - Naming classes and other top-level constructs:
50 - No names should be added to the global namespace. Everything should be
51 in the MOAB namespace. An exception can be made for names with a static
52 scope declared in a .cpp file, but class member functions never have a
53 static scope.
54 - Names should be kept as private as possible. If declaring a struct or
55 utility class that is used internally by some other class, consider
56 defining it in the .cpp file of the main class or a separate header
57 only included in that .cpp file and using (if necessary) only forward
58 delcarations (e.g. \c struct \c Point3D;) in the header file used
59 by other code. If that is not possible, then consider nesting the
60 definitions such that the scope of the name is limited to that of the
61 class using it.
62 - Any names introduced into the top-level MOAB namespace should be
63 sufficiently unique to avoid conflicts with other code. If you must
64 introduce a class to the top-level MOAB namespace, don't choose
65 an overly genereric name like \c Point3D .
66 - Constants and Macros
67 - Don't use a pre-processor macro where a const variable or an inline or
68 template function will suffice.
69 There is absolutely benefit to the former over the later with modern
70 compilers. Further, using macros bypasses typechecking that the compiler
71 would otherwise do for you and if used in headers, introduce names into
72 the global rather than MOAB namespace.
73 - Don't define constants that are already provided by standard libraries.
74 For example, use \c M_PI as defined in \c math.h rather than defining
75 your own constant.
76 \section commits Making Repository Commits
77 As a general rule, developers should update frequently, and commit changes often. However, the repository should always remain
78 in a state where the code can be compiled. Most of the time, the code should also successfully execute "make check" run from the
79 top-level directory. If you commit code that violates this principal, it should be your first priority to return the repository
80 code to a compilable state, and your second priority to make sure "make check" runs without errors.
81
82 Commits to the repository should also come with a non-trivial, useful, non-verbose log message. Oftentimes the best way to generate
83 this message is to run 'commit -a', and include a comment on
84 each file that changed, then Ctrl+O to write out, followed by 'Enter' and Ctrl+X. Many times it is helpful to state that 'make check runs successfully' at the end of the log message.
85 Although it would be possible and many software projects do it, we prefer not to force successful execution of the test suite
86 before every commit. Developers should make every effort to avoid having to impose this constraint, by running a make check
87 before every commit.
88
89 \section git Git Repository Practices
90 As most of our code repositories uses git as the revision control system, it is important to decide on a workflow that can be followed by the individual developer. The way that any individual developer interact with the upstream git repository can have an important impact on other developers and the ability to identify and manage individual changes. This set of guidelines and practices attempts to establish some standards for how developers will interact with the upstream git repository.
91 The Atlassian website <a href="https://www.atlassian.com/git/workflows">describes a number of git workflows</a> , and provides good background reading for a few standard models of such workflows. More important than choosing any one of these workflows precisely are the adoption of some of the concepts embodied within them and understanding the implications of those concepts.
92
93 \subsection outside-master Working Outside the Master Branch
94 A critical concept is that all changes shall be developed outside of the master<sup>1</sup> branch. Whether they are in a different branch of the upstream<sup>2</sup> repository (gitflow) or a branch of an entirely different fork (forking workflow) is secondary. This is a well-established concept regardless of the workflow being adopted, and allows a number of other benefits as described below.
95
96 \subsubsection fork Working on a Different Fork
97 There are a number of benefits of working on a different fork rather than a branch of the upstream repo, although not strictly technical:
98 - Developers, particularly new developers, are liberated from the constant oversight of others as they explore new code options. The impact of this may depend on an individual developer’s personality, but for some it creates a refuge where they can be more free and creative.
99 - Similarly, assuming that all changesets in the upstream repo are communicated to the entire development team, the team is spared a noisy stream of notifications and can focus their attention on the rarer occurrence of a pull request notification.
100
101 \subsubsection pr All Changes are Committed by Pull Request
102 Although this can be imposed technically by limiting the authority to alter the upstream repo (as in the forking workflow), a healthy developer community can also simply rely on convention. The advantage of doing it by convention rather than by restriction is that it is easier to distribute the load of reviewing and accepting changes.
103 A critical consequence of this decision is that all code is reviewed before it is committed to the upstream master branch. This has benefits to overall quality in two related ways:
104 - the code under review will improve due to the review itself, and
105 - those involved in the review will maintain a broad awareness of the code base resulting in better contributions from them.
106
107 This practice does, however, place a substantial burden on the developers to perform timely reviews of the pull requested (PR’ed) code. PR’s that languish without sufficient review have a number of negative consequences:
108 - they need to be refreshed simply to keep them up-to-date with the possibly advancing upstream/master
109 - they may delay further development on similar or related features
110 - they breed frustration in the original developer, undermining the community as a whole.
111 Bitbucket provides powerful collaboration tools that greatly facilitate this process.
112
113 <sup>1</sup> Although a repository may choose a different name for its main development branch, this document will refer to that as the “master” branch.
114
115 <sup>2</sup> For this discussion, the “upstream” repo will refer to the centralized authoritative repository used to synchronize changes.
116
117 \subsection Some Git Mechanics to Keep it Clean
118 Given the above practices, there are some mechanical details that can help ensure that the upstream/master repository is always in a state that facilitates all repository actions and interactions.
119
120 -# Feature branches being used for development should be kept up-to-date with the upstream/master by rebase only. When a feature branch is rebased against the upstream/master, all changes in the upstream/master are inserted into the feature branch at a point in its history that is prior to any of the changes of the feature branch. This can require conflict resultion as the feature branch changes are “replayed” on top of the new upstream/master in its current state. The primary advantage of this policy is that it keeps all of the feature branch changes contiguous. If, by contrast, the upstream/master is merged into the feature branch, the recent changes in the upstream/master become woven into the set of changes in the feature branch. This can make it more difficult to isolate changes later on.
121
122 Strict adoption of this practice is important since a single merge into a feature branch that is then merged back into the upstream/master can make it nearly impossible for others to rebase.
123
124 A typical workflow with pull-request might look like this, all using the command-line, except for submitting the final pull request. Note that there is never a merge operation.
125 -# synchronize your local `master` branch before anything else
126 \code
127 %> git checkout master
128 %> git fetch upstream
129 %> git rebase upstream/master
130 \endcode
131
132 -# now create a new feature branch from master
133 \code
134 %> git checkout -b my_feature_branch master
135 \endcode
136
137 -# now make changes, editing A.cpp, B.hpp, C.cpp
138
139 -# now add/commit your changes to your local feature branch
140 \code
141 %> git add A.cpp B.hpp C.cpp
142 %> git commit -m “Make sure you have a good commit message”
143 \endcode
144 -# push your changes to your feature branch on your fork (often called `origin`)
145 \code
146 %> git push origin my_feature_branch
147 \endcode
148 -# make more changes, editing B.hpp, D.hpp, E.cpp
149
150 -# add/commit your changes to your local feature branch
151 \code
152 %> git add B.hpp D.hpp E.cpp
153 %> git commit -m “Be sure you have another good commit message”
154 \endcode
155 -# push your changes to your freature branch on your fork (often called `origin`)
156 \code
157 %> git push origin my_feature_ranch
158 \endcode
159 -# When you are ready to submit a pull request, be sure that your feature branch is up-to-date. This first step may seem redundant but is here to be clear which branch we are acting on
160 \code
161 %> git checkout my_feature_branch
162 %> git fetch upstream
163 %> git rebase upstream/master
164 \endcode
165 This may generate conflicts that can be addressed at this point.
166
167 NOTE: This step can be performed at any time and should be performed as often as practical to reduce the scope of potential conflicts.
168
169 -# push your updated feature branch on your fork (often called `origin`)
170 \code
171 %> git push origin my_feature_branch
172 \endcode
173 This may require the ‘-f’ option to force the push. (It is frequently necessary to force this push because the act of rebasing will “replay” the commits from the feature branch on top of the master, leading to different commit hashes. Each of the commits will contain the same actual information, but because it has a different set of hashes, git will think there is an inconsistency and ask you to force the change.)
174
175 -# Submit a pull request on Bitbucket, from your fork to the fathomteam fork.
176
177
178 -# When ready to be adopted into the upstream/master, feature branches should be combined by merge only. This adds the changeset to the end of the upstream/master as a set of individual commits but in a contiguous block.
179
180 A typical workflow to merge a pull-request might look like this, all using the command-line.
181 -# synchronize your local `master` branch before anything else (just because it’s never a bad idea!)
182 \code
183 %> git checkout master
184 %> git fetch upstream
185 %> git rebase upstream/master
186 \endcode
187 -# add a remote for the user with the pull-request, perhaps the user is ‘other_user’
188 \code
189 %> git remote add other_user \
190 git@bitbucket.org:other_user/moab.git
191 \endcode
192 -# fetch the other users repo
193 \code
194 %> git fetch other_user
195 \endcode
196 -# check out their feature branch
197 \code
198 %> git checkout -b pr_feature_branch \
199 other_user/feature_branch
200 \endcode
201 -# confirm that it is up-to-date with the master. This first step may seem redundant but is here to be clear which branch we are acting on
202 \code
203 %> git checkout pr_feature_branch
204 %> git fetch upstream
205 %> git rebase upstream/master
206 \endcode
207 This may generate conflicts that can be addressed at this point. You may want to request the original author (other_user) take care of these.
208 -# once confirmed that it’s up-to-date with master, review this branch including:
209 -reading the code
210 -building the code
211 -running tests
212 -# once satisfied that the code meets the necessary standards and that all required/requested changes are fully incorporated into other_users’s feature branch, merge it into master
213 \code
214 %> git checkout master
215 \endcode
216 The next two steps may seem redundant but provide some QA
217 \code
218 %> git fetch upstream
219 %> git rebase upstream/master
220 %> git merge other_user/feature_branch
221 \endcode
222 -# push those changes into the master branch on bitbucket
223 \code
224 %> git push upstream/master
225 \endcode
226
227 -# When a pull request is open for review, any changes to the feature branch will automatically update the pull request. This is the appropriate way for a developer to respond to requests for changes that occur through the PR process.
228
229
230 -# If a developer has ongoing work that is based on a feature branch that is under consideration in an open PR, a new feature branch (B) should be created that is based on the previous feature branch (A). Moreover, as changes are made to the original feature branch (A) due to the review process, the new feature branch (B) should be kept up-to-date by rebase against feature branch (A). This keeps all subsequent changes of (B) downstream from the changes in (A). Once feature branch (A) has been adopted into the upstream/master, the new feature branch (B) can start being rebased against the upstream/master instead.
231
232
233 -# When a repo is forked, its branches are not automatically synchronized with the corresponding branches on the upstream repo. This requires a manual process of synchronization via a local clone. Assuming that the local repo’s branch has the same name as the upstream branch (<branch>), and that the fork is known as “origin”:
234 \code
235 %> git fetch upstream
236 %> git checkout <branch>
237 %> git rebase upstream/<branch>
238 %> git push origin <branch>
239 \endcode
240 The decision of which branches to keep up-to-date is up to the developers. Developers may choose to delete some branches from their own fork to avoid (a) the need to update it and (b) accidentally assuming that it is up-to-date.
241
242
243 -# When rebasing, it is not uncommon to encounter conflicts. This will interrupt the rebasing process, and each conflicted file will contain conflict blocks. You will be offered three choices:
244 - manually resolve the conflicts, add the resolved files with git add, and then git rebase --continue (do not commit the resolved files!)
245 - abort the rebasing process entirely with git rebase --abort
246 - skip the commit that causes the conflict, assuming that you are sure that this is the right thing to do, with git rebase --skip
247
248
249 -# Bitbucket offers a number of buttons/tools to manage changes between branches and forks. Some of these operate in ways that are contrary to the practices recommended here, and others are consistent with these practices. In general, it is best to know how to do all of those operations with the command-line instead of relying on Bitbucket, as it gives you full control over important details.
250
251
252 -# During code development, it might be necessary to work on the same branch on different machines. The workflow to update the local branch is to first fetch the remote changes and then perform a hard reset.
253 \code
254 %> git fetch origin
255 %> git reset --hard origin/branch_name
256 \endcode
257 One should be careful with the branch name as a hard reset would overwrite all changes in the working directory.
258
259
260 */
1.9.1.