You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document provides guidelines for designing and implementing basic tool classes in the ABACUS codebase, focusing on best practices for memory management, code style, and testing. These guidelines apply to all basic mathematical and utility classes, including but not limited to:
6
+
7
+
- vector3.h
8
+
- matrix.h
9
+
- timer.h
10
+
- ndarray.h
11
+
- realarray.h
12
+
- complexarray.h
13
+
- complexmatrix.h
14
+
- matrix3.h
15
+
- intarray.h
16
+
- formatter.h
17
+
- math_chebyshev.h
18
+
19
+
While this guide uses `IntArray` as an example for illustration purposes, the principles and practices described here are applicable to all basic tool classes in ABACUS.
20
+
21
+
## Memory Management
22
+
23
+
### 1. Exception Handling for Memory Allocation
24
+
25
+
Always use try-catch blocks when allocating memory to handle `std::bad_alloc` exceptions gracefully:
26
+
27
+
### 2. Two-Stage Memory Allocation
28
+
29
+
When reallocating memory (e.g., in `create` methods), use a two-stage approach to ensure that the original object remains valid if memory allocation fails.
30
+
31
+
### 3. Null Pointer Checks
32
+
33
+
Always check for null pointers before accessing memory, especially in methods that might be called on objects with failed memory allocation.
34
+
35
+
## Class Design
36
+
37
+
### 1. Copy Constructor
38
+
39
+
Implement a copy constructor to avoid shallow copy issues.
40
+
41
+
### 2. Move Semantics
42
+
43
+
Implement move constructor and move assignment operator to improve performance.
44
+
45
+
### 3. Boundary Checks
46
+
47
+
Add boundary checks to prevent out-of-bounds access.
48
+
49
+
## Code Style
50
+
51
+
### 1. Brace Style
52
+
53
+
Use separate lines for braces, and always use braces for "if" and "for" statements, even if they contain one line of code
54
+
55
+
### 2. Indentation
56
+
57
+
Use spaces instead of tabs for indentation (4 spaces per indent level).
58
+
59
+
### 3. Comments
60
+
61
+
Use English for comments and document important functionality. Follow Doxygen-style documentation for classes and methods.
62
+
63
+
## Code Quality
64
+
65
+
### 1. Named Constants
66
+
67
+
Avoid using magic numbers. Instead, define named constants for numerical values:
68
+
69
+
### 2. Header Includes
70
+
71
+
Ensure all necessary header files are included, especially for functions like `assert`:
72
+
73
+
```cpp
74
+
#include<cassert>
75
+
```
76
+
77
+
## Testing
78
+
79
+
### 1. Unit Tests
80
+
81
+
Write comprehensive unit tests for all classes, including:
82
+
- Constructor tests
83
+
- Method tests
84
+
- Exception handling tests
85
+
- Edge case tests
86
+
87
+
### 2. Test Class Initialization
88
+
89
+
Use constructor initialization lists for test classes to improve compatibility:
90
+
91
+
```cpp
92
+
classIntArrayTest : publictesting::Test
93
+
{
94
+
protected:
95
+
ModuleBase::IntArray a2, a3, a4, a5, a6;
96
+
int aa;
97
+
int bb;
98
+
int count0;
99
+
int count1;
100
+
const int zero;
101
+
102
+
IntArrayTest() : aa(11), bb(1), zero(0)
103
+
{
104
+
}
105
+
};
106
+
```
107
+
108
+
## Best Practices
109
+
110
+
1.**Single Responsibility Principle**: Each class should have a single, well-defined responsibility.
111
+
2.**Encapsulation**: Hide implementation details and expose only necessary interfaces.
112
+
3.**Error Handling**: Handle errors gracefully, especially memory allocation failures.
113
+
4.**Performance**: Use move semantics and other performance optimizations where appropriate.
114
+
5.**Testing**: Write comprehensive tests for all functionality.
0 commit comments