Changes between Version 32 and Version 33 of CodingStyle

Timestamp:

Aug 29, 2019, 6:48:33 PM (5 years ago)

Author:

davea

Comment:

--

CodingStyle

@@ -1 +1 @@
 [[PageOutline]]
 
-= BOINC coding style =
+= Software and information architecture =
+
+Since I first wrote it in 2002, BOINC has evolved continuously and fairly smoothly.
+It's now an extremely powerful system,
+but its code size is fairly small,
+and the code is malleable (easy to change and extend).
+I don't see any barriers to BOINC's continued evolution.
+
+This success is due in large part to BOINC's architecture.
+I'll try to articulate some of the principles behind this architecture.
+
+== Simplicity and brevity ==
+
+The most important principle is: make the code as simple as possible.
+
+To a large extent, shorter is simpler. So:
+
+ * Given two possible implementation, use the shorter one.
+ * If you're writing something new, and it needs a function
+   that might be of general utility,
+   check whether it already exists (in lib/ or html/inc)
+   rather than writing it yourself.
+ * If code is repeated, factor it out and make it into a function.
+   Don't copy and paste code.
+
+Related principles:
+
+ * If you're adding a new mechanism,
+   try to make it more general than the immediate need,
+   without making it more complicated.
+ * If a function becomes longer than 100 lines or so, split it up.
+ * If a file is becoming too big,
+   or has a bunch of unrelated stuff, split it up.
+
+== Uniformity ==
+
+Imitate the style and structure of the code that's already there,
+even if you don't like it.
+
+== Data architecture ==
+
+BOINC stores information in various forms.
+Guidelines:
+
+ * '''MySQL database''': 
+  The DB server is a potential performance bottleneck,
+  and there is a code overhead for DB tables
+  (you need to write interface functions in C++ and/or PHP,
+  and you need to write web pages or scripts for editing data).
+  So use the DB only when it's necessary
+  (e.g. because you need indices for large data) and avoid creating new tables.
+  Don't use referential constraints; instead, check for lookups returning null.
+ * '''XML fields in DB tables''':
+  Simplify DB design by storing information in XML in DB fields
+  (for example, computing preferences and job file lists).
+  This can eliminate the need for separate tables.
+ * '''XML files''':
+  BOINC uses XML format both for internal state (e.g. client_state.xml)
+  and configuration files (cc_config.xml on the client, project.xml on the server).
+  Sometimes we use enclosing tags for multiple items
+  (e.g. <tasks> in project.xml); sometimes we don't.
+  Either is fine - imitate what's already there.
+ * '''PHP and/or C++ code''':
+  If data is used only in PHP, put it in a PHP data structure.
+  You can assume that project admins are able to edit these
+  (e.g. html/project/project.inc).
+
+== Avoid over-engineering ==
+
+If you make a big change to solve a problem that never actually arises,
+that's over-engineering.
+Avoid it.
+
+There are various things (HTTP headers, message boards, XML parsing)
+where we've had to choose between using someone else's library or doing it ourselves.
+There are always tradeoffs.
+If we have something that works and is stable (e.g. XML parsing), leave it.
+
+In general, big changes should be undertaken only if it's certain
+that there's going to be a big reward.
+Big changes introduce bugs, and end up costing more than you think.
+One exception: occasionally I'll make a change whose only effect
+is to shorten or simplify the code.
+
+= Coding style =
 
 == All languages == #all-lang
-
-=== Code factoring === #factoring
-
- * If code is repeated, factor it out and make it into a function.
- * If a function becomes longer than 100 lines or so, split it up.
- * If a file is becoming 'landfill' (unrelated stuff), split it up.
- * C++ `.h` files often contain both interface and implementation. Clearly divide these.
 
 === Error codes === #error-codes
@@ -34 +111 @@
  * All files have a comment at the top saying what's in the file (and perhaps what isn't).
  * Functions are preceded by a comment saying what they do.
- * structs and classes are preceded by a comment saying what they are.
+ * structs and classes are preceded by a comment saying what they represent.
 
 === Naming === #naming
@@ -105 +182 @@
 == C++ specific == #cpp
 
+ * C++ `.h` files often contain both interface and implementation. Clearly divide these.
+
 === Includes === #includes
 
@@ -114 +193 @@
 === Extern declarations === #extern
 
- * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp`
-   .There should be no `extern` statements in `.cpp` files.
+ * `foo.h` should have `extern` declarations for all public functions and variables in `foo.cpp`.
+   There should be no `extern` statements in `.cpp` files.
 
 === Use of static === #static
@@ -123 +202 @@
 === Things to avoid unless there's a compelling reason: === #try-avoid
 
- * Operator or function overloading.
+ * Operator and function overloading.
  * Templates.
+ * Stream I/O; use printf() and scanf().
 
 === Things to avoid === #avoid
@@ -132 +212 @@
    Write a default constructor and a copy constructor instead.
  * Dynamic memory allocation.  Functions shouldn't return pointers to malloc'd items.
-
-
 
 === Structure definitions === #structs
@@ -178 +256 @@
  * Use the [PhpDb database abstraction layer].
  * If a POST or GET value will be used in a database query, use `BoincDb::escape_string` to escape it.
+