Let's create an external specification that is easy to handle

I have noticed that the development of the program is divided. Some modules are easier for newcomers to maintain, while others are not. Modules that are easy to maintain allow you to improve your code the day you join. Modules that do not continue to be perceived as inaccessible, even after months. Create easy-to-use external specifications to reduce your work.

** Features of modules that are easy for newcomers to maintain **

--The external specifications are clear. ――The documentation comments are substantial. --The distinction between the arguments in, out, and inout is clear. @param[in], @param[out] --Const attribute is attached to the argument that can be const attribute. --When defining a function, pass arguments by reference when possible. --Unit tests have been done. --The number of header files to include is limited. --The words are chosen to reduce misunderstandings. -\ #define uses enum type rather than macro constant. --The std :: vector and std :: map types are used. --By using namespaces and classes, the scope of variables is narrowed. --Variable names and item names are organized names. (It wasn't a good name from the beginning, it was renamed after thinking) --Instead of writing the macro definition of the #ifdef macro constant that spans multiple source codes in the source code, write it in CMakeLists.txt, * .sln, * .proj files, etc. By doing so, * .cpp, * .h itself will not be changed. It is better not to change the source code during version control.

** Features of modules that are difficult for newcomers to maintain **

--The external specifications are unclear. ――What is the most effective description of the external specification cannot be traced from the documentation comment of the source code. --Even in documents other than source code, valid documents and documents that are out of date are mixed. --Insufficient documentation comments. --The distinction between the arguments in, out, and inout is unclear. --Even if the argument allows const attribute, const attribute is not attached. --When defining a function, even if it is possible to pass by reference, it is defined by passing by a pointer anyway. --No unit tests have been done. --The number of header files to include will increase anyway. —— Words that are easily misunderstood remain in the documentation comments. ――It is required to understand the module after knowing the whole picture. --\ #define uses macro constants. --Use a fixed size array rather than std :: vector. --Use case statements and if () {} else if () {} else if () {} else {} rather than std :: map type. --Even if it is a cpp file, priority is given to being able to write it within the range of the C language specifications. Therefore, the scope of variables tends to be wide, and many descriptions of global variables and externs remain. ――What is CMake?

I feel empirically that if you first prototype with python, verify the idea, and then define the C ++ specification, it will be a good external specification.

Creating easy-to-use external specifications not only makes it easier to maintain the library, but it also makes it easier for people to use the library.

It's difficult to unit test code that has a lot of externs. If you try to unit test and increase the number of required modules to the link target, you will get out of the unit test. There is a high possibility that there is a problem with the extern outbursts.

Remove extern from C ++ library is created.

Note: Implement an image processing function with an image data structure as an argument in your own library Wrote. I hope it will be a hint when creating a specification.