From 6cc07ac5763f1e640fddedf302c954dbd64f883a Mon Sep 17 00:00:00 2001 From: Daniele Panozzo Date: Sat, 1 Jul 2017 12:20:22 +0100 Subject: [PATCH] added coding guidelines Former-commit-id: 87b4732371394d5f70b951cab79b109502e02092 --- README.md | 18 +++++--- coding-guidelines.html | 62 +++++++++++++++++++++++++++ coding-guidelines.md | 42 ++++++++++++++++++ index.html | 25 ++++++----- optional/index.html | 18 ++++---- scripts/update_gh-pages.sh | 5 ++- tutorial/tutorial.html.REMOVED.git-id | 2 +- 7 files changed, 144 insertions(+), 28 deletions(-) create mode 100644 coding-guidelines.html create mode 100644 coding-guidelines.md diff --git a/README.md b/README.md index 82b954e89..fd190a6c2 100644 --- a/README.md +++ b/README.md @@ -43,10 +43,14 @@ and Windows with Visual Studio 2015 Community Edition. As of version 1.0, libigl includes an introductory [tutorial](http://libigl.github.io/libigl/tutorial/tutorial.html) that covers many functionalities. -## libigl example project +## libigl Example Project We provide a [blank project example](https://github.com/libigl/libigl-example-project) showing how to use libigl and cmake. Feel free and encouraged to copy or fork this project as a way of starting a new personal project using libigl. +## Coding Guidelines and Tips + +libigl follows strict coding guidelines, please take a look [here](style-guidelines.html) before submitting your pull requests. We also have a set of [general coding tips](coding-guidelines.html) on how to code a geometry processing research project. + ## Installation Libigl is a **header-only** library. You do **not** need to build anything to @@ -98,7 +102,7 @@ libigl depends only on the [Eigen](http://eigen.tuxfamily.org) library. For more information see our [tutorial](tutorial/tutorial.html). -### Optional dependencies +### Optional Dependencies Libigl compartmentalizes its **optional** dependences via its directory organization in the `include/` folder. All header files located _directly_ in @@ -106,7 +110,7 @@ the `include/igl/` folder have only stl and Eigen as dependencies. For example, all of the headers that depend on CGAL are located in `include/igl/cgal`. For a full list of _optional_ dependencies check `optional/CMakeLists.txt`. -### GCC and the optional CGAL dependency +### GCC and the Optional CGAL Dependency The `include/igl/cgal/*.h` headers depend on CGAL. It has come to our attention that CGAL does not work properly with GCC 4.8. To the best of our knowledge, GCC 4.7 and clang will work correctly. @@ -162,16 +166,16 @@ git pull git submodule update --recursive ``` -## Unit testing +## Unit Testing Libigl maintains [separate repository](https://github.com/libigl/libigl-unit-tests) for unit testing. -## How to contribute +## How to Contribute If you are interested in joining development, please fork the repository and submit a [pull request](https://help.github.com/articles/using-pull-requests/) -with your changes. +with your changes. libigl follows strict coding guidelines, please take a look at our [style guidelines](style-guidelines.html) before submitting your pull requests. ## License libigl is primarily [MPL2](http://www.mozilla.org/MPL/2.0/) licensed @@ -255,7 +259,7 @@ If you find bugs or have problems please use our [github issue tracking page](https://github.com/libigl/libigl/issues). ## Copyright -2016 Alec Jacobson, Daniele Panozzo, Christian Schüller, Olga Diamanti, Qingnan +2017 Alec Jacobson, Daniele Panozzo, Christian Schüller, Olga Diamanti, Qingnan Zhou, Sebastian Koch, Amir Vaxman, Nico Pietroni, Stefan Brugger, Kenshi Takayama, Wenzel Jakob, Nikolas De Giorgis, Luigi Rocca, Leonardo Sacht, Kevin Walliman, Olga Sorkine-Hornung, and others. diff --git a/coding-guidelines.html b/coding-guidelines.html new file mode 100644 index 000000000..5352d4c52 --- /dev/null +++ b/coding-guidelines.html @@ -0,0 +1,62 @@ + + + + + libigl + + + + + + + + + +

Libigl Coding Tips (aka “How to code a SIGGRAPH project”)

+ +

This is a short list of coding tips that will greatly reduce your pain and suffering before (and after) the SIGGRAPH deadline.

+ +

1. Serialize it all

+ +

The entire state of your application should be serializable, i.e. It should be possible to save it into a binary file and reload it at any point. This drastically simplifies debugging, since you can serialize just before a crash happens and debug from that point without running your complete algorithm again. Serializing all results shown in the paper’s figures enables quicker editing iterations before (and after) the deadline. It also allows you to share your results with others that wish to compare with your method. An additional tip is to serialize the state of the application on the window close event and automatically reload it when you launch it again.

+ +

2. Always assert

+ +

Even if you know what you are doing, always assert, you will be surprised. Assertion is a powerful but underused feature available in all programming languages. It is essential for writing research code since often you will have to implement algorithms that turns out to not be doing what you expect: in these cases it is important to know if the algorithm is flawed or if there is a bug in your implementation. Discarding a good idea because of a coding bug is frustrating and unfortunately common. Assertion is an ideal way to reduce the chances of introducing bugs in your code and, differently from unit testing, requires a very minor programming effort. You should use them extensively.

+ +

3. Plot everything

+ +

If you can visually plot the results or some intermediate steps of your algorithm, do it, even if you think your implementation is correct! It is a lot easier to find bugs or to get an intuition on an algorithm by looking at a plot than by looking at the code.

+ +

4. If the compilation time after a code change is more than five seconds, you are doing it wrong

+ +

You will change your code hundreds of times every day for months. Let’s say that you will change it a hundred times a day (which is a very conservative estimate): if the compilation takes one minute, you will waste almost two hours every day, just waiting! What is even worse, is that since it is only 1–2 minutes at a time, it will not even be sufficient to prepare a coffee. Spend the hour or two that is needed to get your code to compile in a few seconds, you will benefit from it in the same day already, and the time saved over an entire project will be gigantic.

+ +

5. Commit often (and with a meaningful description)

+ +

Use a distributed version control system (git,hg), and keep the repository on a remote host. Commit often and put meaningful comments. This will serve you as an emergency backup and it will always allow you to have a running version of your code whenever your advisor is passing by and asking to see some results. She will be impressed and you will not have to quickly fix your build with your boss breathing down your neck.

+ +

6. Dependencies are evil, avoid them

+ +

Keep your code simple and with minimal external dependencies. Spending a day or two to code something from scratch while avoiding to use third party code is usually an investment that pays off. The more code you have in your algorithm that is not written by you, the harder debugging becomes. In particular, refrain from building your entire project on code that you do not understand to avoid bad surprises just before the deadline. If you must use code written by others, spend the time that is needed to fully understand what it does, and link it statically so that it will be easy to place breakpoints inside it.

+ +

7. Global variables are not evil, use them

+ +

Global variables are often extremely useful — if you think you need one, use it. They are indeed dangerous for large projects, but you are not coding one of those, you are coding a prototype to test a research idea. I suggest to keep one single copy of your entire application state in a global variable (or a singleton class) that can be serialized (see tip 1). This variable should include everything rendered on screen and all the temporary data produced by your algorithm. This will allow you to easily access all the data in your project for plotting or debugging purposes.

+ +

8. Prototype first

+ +

Don’t preemptively optimize and try to quickly write code that is clean and correct. It is common to try multiple different approaches to solve a new problem before finding the right one. This means that the majority of the code that you will write will not be used at the end of the project. While you should still write high-quality and bug-free code to make sure that your results is correct, you definitely do not want to spend time optimizing it before you are sure that is the right approach. In particular, it is helpful to learn a good prototyping language (Python, matlab) and use it for the early stages of the project and switch to (or mix it with) c++ only after finding a promising direction.

+ +

9. Avoid explicit pointers

+ +

Do yourself a favor, do not use explicit pointers. If you use a language that supports explicit pointers, use them only if you really have to. And even in that case, keep them isolated in a single file and be very careful with them. Writing data inside another variable by accident might not trigger a crash, and simply produce strange artifacts that might convince you that a promising research direction does not work, while the problem lies in a nasty bug in your code. There is no reason to take that risk during prototyping, just avoid them and leave them for the end of the project in case they become necessary to optimize your code.

+ +

10. If your program crashes, fix it now!

+ +

If your program crashes, don’t close your eyes and move on. Try to make it happen again, debug it and fix it immediately. These bugs are a nightmare to find, and the more code you add on top of a bug will just make it harder to find. If you don’t fix it, due to Murphy’s law, it will start to be problematic only a few days before the deadline and you will have no time to fix it at that point.

+ +

Daniele Panozzo

+ + + diff --git a/coding-guidelines.md b/coding-guidelines.md new file mode 100644 index 000000000..9cf8038e1 --- /dev/null +++ b/coding-guidelines.md @@ -0,0 +1,42 @@ +# Libigl Coding Tips (aka "How to code a SIGGRAPH project") + +This is a short list of coding tips that will greatly reduce your pain and suffering before (and after) the SIGGRAPH deadline. + + +### 1. Serialize it all +The entire state of your application should be serializable, i.e. It should be possible to save it into a binary file and reload it at any point. This drastically simplifies debugging, since you can serialize just before a crash happens and debug from that point without running your complete algorithm again. Serializing all results shown in the paper's figures enables quicker editing iterations before (and after) the deadline. It also allows you to share your results with others that wish to compare with your method. An additional tip is to serialize the state of the application on the window close event and automatically reload it when you launch it again. + +### 2. Always assert +Even if you know what you are doing, always assert, you will be surprised. Assertion is a powerful but underused feature available in all programming languages. It is essential for writing research code since often you will have to implement algorithms that turns out to not be doing what you expect: in these cases it is important to know if the algorithm is flawed or if there is a bug in your implementation. Discarding a good idea because of a coding bug is frustrating and unfortunately common. Assertion is an ideal way to reduce the chances of introducing bugs in your code and, differently from unit testing, requires a very minor programming effort. You should use them extensively. + +### 3. Plot everything + +If you can visually plot the results or some intermediate steps of your algorithm, do it, even if you think your implementation is correct! It is a lot easier to find bugs or to get an intuition on an algorithm by looking at a plot than by looking at the code. + +### 4. If the compilation time after a code change is more than five seconds, you are doing it wrong + +You will change your code hundreds of times every day for months. Let's say that you will change it a hundred times a day (which is a very conservative estimate): if the compilation takes one minute, you will waste almost two hours every day, just waiting! What is even worse, is that since it is only 1-2 minutes at a time, it will not even be sufficient to prepare a coffee. Spend the hour or two that is needed to get your code to compile in a few seconds, you will benefit from it in the same day already, and the time saved over an entire project will be gigantic. + +### 5. Commit often (and with a meaningful description) + +Use a distributed version control system (git,hg), and keep the repository on a remote host. Commit often and put meaningful comments. This will serve you as an emergency backup and it will always allow you to have a running version of your code whenever your advisor is passing by and asking to see some results. She will be impressed and you will not have to quickly fix your build with your boss breathing down your neck. + +### 6. Dependencies are evil, avoid them + +Keep your code simple and with minimal external dependencies. Spending a day or two to code something from scratch while avoiding to use third party code is usually an investment that pays off. The more code you have in your algorithm that is not written by you, the harder debugging becomes. In particular, refrain from building your entire project on code that you do not understand to avoid bad surprises just before the deadline. If you must use code written by others, spend the time that is needed to fully understand what it does, and link it statically so that it will be easy to place breakpoints inside it. + +### 7. Global variables are not evil, use them + +Global variables are often extremely useful --- if you think you need one, use it. They are indeed dangerous for large projects, but you are not coding one of those, you are coding a prototype to test a research idea. I suggest to keep one single copy of your entire application state in a global variable (or a singleton class) that can be serialized (see tip 1). This variable should include everything rendered on screen and all the temporary data produced by your algorithm. This will allow you to easily access all the data in your project for plotting or debugging purposes. + +### 8. Prototype first +Don’t preemptively optimize and try to quickly write code that is clean and correct. It is common to try multiple different approaches to solve a new problem before finding the right one. This means that the majority of the code that you will write will not be used at the end of the project. While you should still write high-quality and bug-free code to make sure that your results is correct, you definitely do not want to spend time optimizing it before you are sure that is the right approach. In particular, it is helpful to learn a good prototyping language (Python, matlab) and use it for the early stages of the project and switch to (or mix it with) c++ only after finding a promising direction. + +### 9. Avoid explicit pointers +Do yourself a favor, do not use explicit pointers. If you use a language that supports explicit pointers, use them only if you really have to. And even in that case, keep them isolated in a single file and be very careful with them. Writing data inside another variable by accident might not trigger a crash, and simply produce strange artifacts that might convince you that a promising research direction does not work, while the problem lies in a nasty bug in your code. There is no reason to take that risk during prototyping, just avoid them and leave them for the end of the project in case they become necessary to optimize your code. + +### 10. If your program crashes, fix it now! + +If your program crashes, don't close your eyes and move on. Try to make it happen again, debug it and fix it immediately. These bugs are a nightmare to find, and the more code you add on top of a bug will just make it harder to find. If you don't fix it, due to Murphy's law, it will start to be problematic only a few days before the deadline and you will have no time to fix it at that point. + +_Daniele Panozzo_ diff --git a/index.html b/index.html index a8e86c112..5911bd835 100644 --- a/index.html +++ b/index.html @@ -15,7 +15,7 @@

libigl - A simple C++ geometry processing library

Build Status -Build status +Build status

https://github.com/libigl/libigl/

@@ -59,10 +59,14 @@ and Windows with Visual Studio 2015 Community Edition.

As of version 1.0, libigl includes an introductory tutorial that covers many functionalities.

-

libigl example project

+

libigl Example Project

We provide a blank project example showing how to use libigl and cmake. Feel free and encouraged to copy or fork this project as a way of starting a new personal project using libigl.

+

Coding Guidelines and Tips

+ +

libigl follows strict coding guidelines, please take a look here before submitting your pull requests. We also have a set of general coding tips on how to code a geometry processing research project.

+

Installation

Libigl is a header-only library. You do not need to build anything to @@ -112,7 +116,7 @@ libigl depends only on the Eigen librar

For more information see our tutorial.

-

Optional dependencies

+

Optional Dependencies

Libigl compartmentalizes its optional dependences via its directory organization in the include/ folder. All header files located directly in @@ -120,7 +124,7 @@ the include/igl/ folder have only stl and Eigen as dependencies. Fo all of the headers that depend on CGAL are located in include/igl/cgal. For a full list of optional dependencies check optional/CMakeLists.txt.

-

GCC and the optional CGAL dependency

+

GCC and the Optional CGAL Dependency

The include/igl/cgal/*.h headers depend on CGAL. It has come to our attention that CGAL does not work properly with GCC 4.8. To the best of our knowledge, @@ -178,16 +182,16 @@ subrepos:

git submodule update --recursive -

Unit testing

+

Unit Testing

Libigl maintains separate repository for unit testing.

-

How to contribute

+

How to Contribute

If you are interested in joining development, please fork the repository and submit a pull request -with your changes.

+with your changes. libigl follows strict coding guidelines, please take a look at our style guidelines before submitting your pull requests.

License

@@ -232,7 +236,8 @@ few labs/companies/institutions using libigl:

  • ETH Zurich, Interactive Geometry Lab and Advanced Technologies Lab, Swizterland
  • George Mason University, CraGL, USA
  • Hong Kong University of Science and Technology, Hong Kong
    • -
  • [Inria](Université Grenoble Alpes), France
    • +
  • Inria, Université Grenoble Alpes, France
    • +
  • Jiangnan university, China
  • National Institute of Informatics, Japan
  • New York University, Media Research Lab, USA
  • NYUPoly, Game Innovation Lab, USA
    • @@ -257,7 +262,7 @@ few labs/companies/institutions using libigl:

    Contact

    -

    Libigl is a group endeavor led by Alec +

    Libigl is a group endeavor led by Alec Jacobson and Daniele Panozzo. Please contact us if you have @@ -274,7 +279,7 @@ page.

    -

    2016 Alec Jacobson, Daniele Panozzo, Christian Schüller, Olga Diamanti, Qingnan +

    2017 Alec Jacobson, Daniele Panozzo, Christian Schüller, Olga Diamanti, Qingnan Zhou, Sebastian Koch, Amir Vaxman, Nico Pietroni, Stefan Brugger, Kenshi Takayama, Wenzel Jakob, Nikolas De Giorgis, Luigi Rocca, Leonardo Sacht, Kevin Walliman, Olga Sorkine-Hornung, and others.

    diff --git a/optional/index.html b/optional/index.html index 38fcac0e7..f846aa016 100644 --- a/optional/index.html +++ b/optional/index.html @@ -146,12 +146,12 @@ containing Eigen matrices and other standard simple data-structures.

    git archive -prefix=libigl/ -o libigl.zip master
    -

    Explicit specialization of templated functions

    +

    Explicit instantiations of templated functions

    Special care must be taken by the developers of each function and class in the libigl library that uses C++ templates. If this function is intended to be compiled into the statically linked libigl library -then function is only compiled for each explicitly specialized +then function is only compiled for each explicitly instantiated declaration. These should be added at the bottom of the corresponding .cpp file surrounded by a

    @@ -159,8 +159,8 @@ declaration. These should be added at the bottom of the corresponding

    Of course, a developer may not know ahead of time which -specializations should be explicitly included in the igl static lib. -One way to find out is to add one explicit specialization for each +instantiations should be explicitly included in the igl static lib. +One way to find out is to add one explicit instantiation for each call in one’s own project. This only ever needs to be done once for each template.

    @@ -168,7 +168,7 @@ each template.

    output.

    Supposed for example we have compiled the igl static lib, including the -cat.h and cat.cpp functions, without any explicit instanciation. Say +cat.h and cat.cpp functions, without any explicit instantiation. Say using the makefile in the libigl directory:

    cd $LIBIGL
@@ -193,13 +193,13 @@ all. Just copy the first part in quotes

    , then append it -to the list of explicit template specializations at the end of +to the list of explicit template instantiations at the end of cat.cpp after the word template and followed by a semi-colon. Like this:

    #ifdef IGL_STATIC_LIBRARY
-// Explicit template specialization
+// Explicit template instantiation
 template Eigen::Matrix<int, -1, -1, 0, -1, -1> igl::cat<Eigen::Matrix<int, -1, -1, 0, -1, -1> >(int, Eigen::Matrix<int, -1, -1, 0, -1, -1> const&, Eigen::Matrix<int, -1, -1, 0, -1, -1> const&);
 #endif
    @@ -215,7 +215,7 @@ process until no more symbols are undefined.

    It may be useful to check that you code compiles with no errors first using the headers-only version to be sure that all errors are from missing template -specializations.

    +instantiations.

    If you’re using make then the following command will reveal each missing symbol on its own line:

    @@ -225,7 +225,7 @@ reveal each missing symbol on its own line:

    Alternatively you can use the autoexplicit.sh function which (for well organized .h/.cpp pairs in libigl) automatically -create explicit instanciations from your compiler’s error messages. +create explicit instantiations from your compiler’s error messages. Repeat this process until convergence:

    cd /to/your/project
diff --git a/scripts/update_gh-pages.sh b/scripts/update_gh-pages.sh
index bf4d7aef2..73c8ce31a 100755
--- a/scripts/update_gh-pages.sh
+++ b/scripts/update_gh-pages.sh
@@ -16,7 +16,7 @@ echo "$HEADER" \
   | cat - README.md | multimarkdown -o index.html
 
 echo "$HEADER" \
-  | cat - style-guidelines.md | multimarkdown -o style-guidelines.html 
+  | cat - style-guidelines.md | multimarkdown -o style-guidelines.html
 
 HEADER="title: libigl
 author: Alec Jacobson and Daniele Panozzo and others
@@ -32,3 +32,6 @@ echo "$HEADER" \
   | cat - optional/README.md | multimarkdown -o optional/index.html
 
 multimarkdown tutorial/tutorial.md -o tutorial/tutorial.html
+
+echo "$HEADER" \
+  | cat - coding-guidelines.md | multimarkdown -o coding-guidelines.html
diff --git a/tutorial/tutorial.html.REMOVED.git-id b/tutorial/tutorial.html.REMOVED.git-id
index 3c77daea7..1a6667aef 100644
--- a/tutorial/tutorial.html.REMOVED.git-id
+++ b/tutorial/tutorial.html.REMOVED.git-id
@@ -1 +1 @@
-e433fea7c89195d4086db16774eec2e6a7e8014f
\ No newline at end of file
+b216f50907a0c99d0cf2121123faff1aa75755bb
\ No newline at end of file