From patchwork Sat Dec 11 17:58:22 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas Schwinge X-Patchwork-Id: 48831 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 42FE33857815 for ; Sat, 11 Dec 2021 17:58:44 +0000 (GMT) X-Original-To: libabigail@sourceware.org Delivered-To: libabigail@sourceware.org Received: from smtprelay04.ispgateway.de (smtprelay04.ispgateway.de [80.67.18.16]) by sourceware.org (Postfix) with ESMTPS id 024F53858D39 for ; Sat, 11 Dec 2021 17:58:38 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 024F53858D39 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=codesourcery.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=schwinge.name Received: from [192.94.31.2] (helo=dem-tschwing-1.ger.mentorg.com) by smtprelay04.ispgateway.de with esmtpsa (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1mw6da-0005Kq-QT; Sat, 11 Dec 2021 18:58:22 +0100 Received: (nullmailer pid 950900 invoked by uid 1000); Sat, 11 Dec 2021 17:58:35 -0000 From: Thomas Schwinge To: libabigail@sourceware.org, Dodji Seketeli Subject: [PATCH] CONTRIBUTING: Move "Coding language and style" section Date: Sat, 11 Dec 2021 18:58:22 +0100 Message-Id: <20211211175822.950836-1-thomas@codesourcery.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <86ft4nowan.fsf@redhat.com> References: <86ft4nowan.fsf@redhat.com> MIME-Version: 1.0 X-Df-Sender: b3V0Z29pbmdAc2Nod2luZ2UubmFtZQ== X-Spam-Status: No, score=-11.2 required=5.0 tests=BAYES_00, GIT_PATCH_0, HEADER_FROM_DIFFERENT_DOMAINS, KAM_ASCII_DIVIDERS, KAM_DMARC_STATUS, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: libabigail@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list of the Libabigail project List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , Cc: Thomas Schwinge Errors-To: libabigail-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libabigail" This section got added in commit 4f8c9b170d80b920d13e8f291b347df74db34307 "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 --- CONTRIBUTING | 110 +++++++++++++++++++++++++-------------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git CONTRIBUTING CONTRIBUTING index 3a2073b3..24a483b2 100644 --- CONTRIBUTING +++ CONTRIBUTING @@ -99,61 +99,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 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 -------------------------------------- @@ -229,6 +174,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 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 ==============