RepoMirrors/libabigail
1
0
Fork 0
mirror of git://sourceware.org/git/libabigail.git synced 2024-12-15 06:24:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

CONTRIBUTING: Move "Coding language and style" section

Browse Source 
This section got added in commit 4f8c9b170d
"Use C++11 for the code base", but unfortunately got placed in the middle
of the "Regression tests" section.  Move it after that one.

	* CONTRIBUTING: Move "Coding language and style" section.

Signed-off-by: Thomas Schwinge <thomas@codesourcery.com>
This commit is contained in:
Thomas Schwinge 2021-12-11 18:58:22 +01:00 committed by Dodji Seketeli
parent 21e0280a8d
commit 544d8b60ab
1 changed files with 55 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
CONTRIBUTING
View File

@ -98,61 +98,6 @@ So, to be complete the regression checking command to run against your
patch should be: "make check-self-compare distcheck-fast -j16", if you have
a machine with a 16 threads processors, for instance.
Coding language and style
==========================
The coding style is self evident when reading the source code. So
please, stick to and mimic what is already in there for the sake of
consistency at very least. Just for history, it's derived from the
style of the C++ standard library from the GNU project.
As of libabigail 2.0, the language we use is C++ 11. The level
supported is the one supported by the GCC 4.8.x series of compilers.
This should be old and well tested enough to be supported by your
current favorite compiler.
Initially, the code base of the project was written in C++03, with the
TR1 extensions. That heritage is well visible in the code base as it
is today.
Please do not rush and send gazillions of patches that just re-write
tons of code into your favorite C++ 11 flavour du jour. We will
likely reject those patches. We want to keep the history of the code
base in such a way that tools like "git blame <sourcefile> are still
useful.
So we'll accept patches changing parts of the code base to more recent
C++ 11 constructs only if you happen to add functionality or fix
things in that area. If it makes "cultural common" sense to adopt
those constructs. What I mean by "cultural" is that must make sense
in relative to the culture of the project. And yes, that is
subjective. Sorry.
As a generic rule, we tend to favor the lowest possible level of
abstraction that makes sense without requiring future maintainers of
the project to have a PhD in design patterns. We are not impressed by
design patterns. We use them where they make clear sense, but we
don't idolize them. Put it another way, we will always favor the one
who *READS* and debug the code over the one who writes it. To put
things in a hypothetical perspective, we'll rather accept a repetitive
code that stays simple to read and debug over a highly abstract one
using meta programming to save a few lines of repetitive code located
in a very small number of places.
Really, in this project, we care about low level binary analysis
stuff. Issues in that area can be hard to reproduce and quite
challenging to debug. So having tons of abstraction layers in the
code base have proven to be a maintenance burden over the years, from
our experience in working on similar projects. So please help us
avoid those mistakes that we make just for the pleasure of writing
what can look as "pleasant code" at a first naive sight.
That being said, we also love cleanly designed APIs that are fairly
re-usable and well documented. And we also praise abstraction and
modularisation that we recognize as being the most basic tools of any
engineer. So we like to think about ourselves as well rounded people
who care about maintaining things for a long time to come :-)
Launching regression tests in Valgrind
--------------------------------------
@ -228,6 +173,61 @@ make sure to add your new test input files to the
tests/data/Makefile.am file, in the EXTRA_DIST variable. Look at how
things are organized in that file, and please do things similarly.
Coding language and style
==========================
The coding style is self evident when reading the source code. So
please, stick to and mimic what is already in there for the sake of
consistency at very least. Just for history, it's derived from the
style of the C++ standard library from the GNU project.
As of libabigail 2.0, the language we use is C++ 11. The level
supported is the one supported by the GCC 4.8.x series of compilers.
This should be old and well tested enough to be supported by your
current favorite compiler.
Initially, the code base of the project was written in C++03, with the
TR1 extensions. That heritage is well visible in the code base as it
is today.
Please do not rush and send gazillions of patches that just re-write
tons of code into your favorite C++ 11 flavour du jour. We will
likely reject those patches. We want to keep the history of the code
base in such a way that tools like "git blame <sourcefile> are still
useful.
So we'll accept patches changing parts of the code base to more recent
C++ 11 constructs only if you happen to add functionality or fix
things in that area. If it makes "cultural common" sense to adopt
those constructs. What I mean by "cultural" is that must make sense
in relative to the culture of the project. And yes, that is
subjective. Sorry.
As a generic rule, we tend to favor the lowest possible level of
abstraction that makes sense without requiring future maintainers of
the project to have a PhD in design patterns. We are not impressed by
design patterns. We use them where they make clear sense, but we
don't idolize them. Put it another way, we will always favor the one
who *READS* and debug the code over the one who writes it. To put
things in a hypothetical perspective, we'll rather accept a repetitive
code that stays simple to read and debug over a highly abstract one
using meta programming to save a few lines of repetitive code located
in a very small number of places.
Really, in this project, we care about low level binary analysis
stuff. Issues in that area can be hard to reproduce and quite
challenging to debug. So having tons of abstraction layers in the
code base have proven to be a maintenance burden over the years, from
our experience in working on similar projects. So please help us
avoid those mistakes that we make just for the pleasure of writing
what can look as "pleasant code" at a first naive sight.
That being said, we also love cleanly designed APIs that are fairly
re-usable and well documented. And we also praise abstraction and
modularisation that we recognize as being the most basic tools of any
engineer. So we like to think about ourselves as well rounded people
who care about maintaining things for a long time to come :-)
Sign your work
==============