This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[doc RFA] Clean up coding standards, add python coding standards.


Hi.

This patch does a couple of things.

I think it is wrong that a discussion of cleanups appears in the same
chapter as coding standards.  Ditto for a few other subsections
in the existing Coding chapter.

This patch creates a new Coding Standards chapter to put such things in,
and I've added a section on Python coding standards.

I'm not happy with the name "Miscellaneous Coding Guidelines" but it
works well enough for me.  Feel free to suggest an alternatives.

Ok to check in?

2010-10-19  Doug Evans  <dje@google.com>

	* gdbint.texinfo (Miscellaneous Coding Guidelines): Renamed from
	Coding.  All references updated.
	(Coding Standards): New chapter.  Move the coding standard related
	subsections here.  Add section on Python coding standards.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.326
diff -u -p -r1.326 gdbint.texinfo
--- gdbint.texinfo	22 Jun 2010 05:03:19 -0000	1.326
+++ gdbint.texinfo	19 Oct 2010 15:48:33 -0000
@@ -83,7 +83,8 @@ as the mechanisms that adapt @value{GDBN
 * Target Vector Definition::
 * Native Debugging::
 * Support Libraries::
-* Coding::
+* Miscellaneous Coding Guidelines::
+* Coding Standards::
 * Porting GDB::
 * Versions and Branches::
 * Start of New Year Procedure::
@@ -1322,9 +1323,9 @@ be signaled.
 
 @deftypefun {struct cleanup *} make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
 This function first opens the tuple and then establishes a cleanup
-(@pxref{Coding, Cleanups}) to close the tuple.  It provides a convenient
-and correct implementation of the non-portable@footnote{The function
-cast is not portable ISO C.} code sequence:
+(@pxref{Miscellaneous Coding Guidelines, Cleanups}) to close the tuple.
+It provides a convenient and correct implementation of the
+non-portable@footnote{The function cast is not portable ISO C.} code sequence:
 @smallexample
 struct cleanup *old_cleanup;
 ui_out_tuple_begin (uiout, "...");
@@ -1349,7 +1350,8 @@ be signaled.
 
 @deftypefun {struct cleanup *} make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
 Similar to @code{make_cleanup_ui_out_tuple_begin_end}, this function
-opens a list and then establishes cleanup (@pxref{Coding, Cleanups})
+opens a list and then establishes cleanup
+(@pxref{Miscellaneous Coding Guidelines, Cleanups})
 that will close the list.
 @end deftypefun
 
@@ -5756,9 +5758,9 @@ Binary search the array.
 
 @section include
 
-@node Coding
+@node Miscellaneous Coding Guidelines
 
-@chapter Coding
+@chapter Miscellaneous Coding Guidelines
 
 This chapter covers topics that are lower-level than the major
 algorithms of @value{GDBN}.
@@ -5995,27 +5997,6 @@ finish by printing a newline, to flush t
 to unfiltered (@code{printf}) output.  Symbol reading routines that
 print warnings are a good example.
 
-@section @value{GDBN} Coding Standards
-@cindex coding standards
-
-@value{GDBN} follows the GNU coding standards, as described in
-@file{etc/standards.texi}.  This file is also available for anonymous
-FTP from GNU archive sites.  @value{GDBN} takes a strict interpretation
-of the standard; in general, when the GNU standard recommends a practice
-but does not require it, @value{GDBN} requires it.
-
-@value{GDBN} follows an additional set of coding standards specific to
-@value{GDBN}, as described in the following sections.
-
-
-@subsection ISO C
-
-@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
-compiler.
-
-@value{GDBN} does not assume an ISO C or POSIX compliant C library.
-
-
 @subsection Memory Management
 
 @value{GDBN} does not use the functions @code{malloc}, @code{realloc},
@@ -6109,6 +6090,186 @@ currently too noisy to enable with @samp
 
 @end table
 
+@subsection Internal Error Recovery
+
+During its execution, @value{GDBN} can encounter two types of errors.
+User errors and internal errors.  User errors include not only a user
+entering an incorrect command but also problems arising from corrupt
+object files and system errors when interacting with the target.
+Internal errors include situations where @value{GDBN} has detected, at
+run time, a corrupt or erroneous situation.
+
+When reporting an internal error, @value{GDBN} uses
+@code{internal_error} and @code{gdb_assert}.
+
+@value{GDBN} must not call @code{abort} or @code{assert}.
+
+@emph{Pragmatics: There is no @code{internal_warning} function.  Either
+the code detected a user error, recovered from it and issued a
+@code{warning} or the code failed to correctly recover from the user
+error and issued an @code{internal_error}.}
+
+@subsection Command Names
+
+GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}.
+
+@subsection Clean Design and Portable Implementation
+
+@cindex design
+In addition to getting the syntax right, there's the little question of
+semantics.  Some things are done in certain ways in @value{GDBN} because long
+experience has shown that the more obvious ways caused various kinds of
+trouble.
+
+@cindex assumptions about targets
+You can't assume the byte order of anything that comes from a target
+(including @var{value}s, object files, and instructions).  Such things
+must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
+@value{GDBN}, or one of the swap routines defined in @file{bfd.h},
+such as @code{bfd_get_32}.
+
+You can't assume that you know what interface is being used to talk to
+the target system.  All references to the target must go through the
+current @code{target_ops} vector.
+
+You can't assume that the host and target machines are the same machine
+(except in the ``native'' support modules).  In particular, you can't
+assume that the target machine's header files will be available on the
+host machine.  Target code must bring along its own header files --
+written from scratch or explicitly donated by their owner, to avoid
+copyright problems.
+
+@cindex portability
+Insertion of new @code{#ifdef}'s will be frowned upon.  It's much better
+to write the code portably than to conditionalize it for various
+systems.
+
+@cindex system dependencies
+New @code{#ifdef}'s which test for specific compilers or manufacturers
+or operating systems are unacceptable.  All @code{#ifdef}'s should test
+for features.  The information about which configurations contain which
+features should be segregated into the configuration files.  Experience
+has proven far too often that a feature unique to one particular system
+often creeps into other systems; and that a conditional based on some
+predefined macro for your current system will become worthless over
+time, as new versions of your system come out that behave differently
+with regard to this feature.
+
+Adding code that handles specific architectures, operating systems,
+target interfaces, or hosts, is not acceptable in generic code.
+
+@cindex portable file name handling
+@cindex file names, portability
+One particularly notorious area where system dependencies tend to
+creep in is handling of file names.  The mainline @value{GDBN} code
+assumes Posix semantics of file names: absolute file names begin with
+a forward slash @file{/}, slashes are used to separate leading
+directories, case-sensitive file names.  These assumptions are not
+necessarily true on non-Posix systems such as MS-Windows.  To avoid
+system-dependent code where you need to take apart or construct a file
+name, use the following portable macros:
+
+@table @code
+@findex HAVE_DOS_BASED_FILE_SYSTEM
+@item HAVE_DOS_BASED_FILE_SYSTEM
+This preprocessing symbol is defined to a non-zero value on hosts
+whose filesystems belong to the MS-DOS/MS-Windows family.  Use this
+symbol to write conditional code which should only be compiled for
+such hosts.
+
+@findex IS_DIR_SEPARATOR
+@item IS_DIR_SEPARATOR (@var{c})
+Evaluates to a non-zero value if @var{c} is a directory separator
+character.  On Unix and GNU/Linux systems, only a slash @file{/} is
+such a character, but on Windows, both @file{/} and @file{\} will
+pass.
+
+@findex IS_ABSOLUTE_PATH
+@item IS_ABSOLUTE_PATH (@var{file})
+Evaluates to a non-zero value if @var{file} is an absolute file name.
+For Unix and GNU/Linux hosts, a name which begins with a slash
+@file{/} is absolute.  On DOS and Windows, @file{d:/foo} and
+@file{x:\bar} are also absolute file names.
+
+@findex FILENAME_CMP
+@item FILENAME_CMP (@var{f1}, @var{f2})
+Calls a function which compares file names @var{f1} and @var{f2} as
+appropriate for the underlying host filesystem.  For Posix systems,
+this simply calls @code{strcmp}; on case-insensitive filesystems it
+will call @code{strcasecmp} instead.
+
+@findex DIRNAME_SEPARATOR
+@item DIRNAME_SEPARATOR
+Evaluates to a character which separates directories in
+@code{PATH}-style lists, typically held in environment variables.
+This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
+
+@findex SLASH_STRING
+@item SLASH_STRING
+This evaluates to a constant string you should use to produce an
+absolute filename from leading directories and the file's basename.
+@code{SLASH_STRING} is @code{"/"} on most systems, but might be
+@code{"\\"} for some Windows-based ports.
+@end table
+
+In addition to using these macros, be sure to use portable library
+functions whenever possible.  For example, to extract a directory or a
+basename part from a file name, use the @code{dirname} and
+@code{basename} library functions (available in @code{libiberty} for
+platforms which don't provide them), instead of searching for a slash
+with @code{strrchr}.
+
+Another way to generalize @value{GDBN} along a particular interface is with an
+attribute struct.  For example, @value{GDBN} has been generalized to handle
+multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
+by defining the @code{target_ops} structure and having a current target (as
+well as a stack of targets below it, for memory references).  Whenever
+something needs to be done that depends on which remote interface we are
+using, a flag in the current target_ops structure is tested (e.g.,
+@code{target_has_stack}), or a function is called through a pointer in the
+current target_ops structure.  In this way, when a new remote interface
+is added, only one module needs to be touched---the one that actually
+implements the new remote interface.  Other examples of
+attribute-structs are BFD access to multiple kinds of object file
+formats, or @value{GDBN}'s access to multiple source languages.
+
+Please avoid duplicating code.  For example, in @value{GDBN} 3.x all
+the code interfacing between @code{ptrace} and the rest of
+@value{GDBN} was duplicated in @file{*-dep.c}, and so changing
+something was very painful.  In @value{GDBN} 4.x, these have all been
+consolidated into @file{infptrace.c}.  @file{infptrace.c} can deal
+with variations between systems the same way any system-independent
+file would (hooks, @code{#if defined}, etc.), and machines which are
+radically different don't need to use @file{infptrace.c} at all.
+
+All debugging code must be controllable using the @samp{set debug
+@var{module}} command.  Do not use @code{printf} to print trace
+messages.  Use @code{fprintf_unfiltered(gdb_stdlog, ...}.  Do not use
+@code{#ifdef DEBUG}.
+
+@node Coding Standards
+
+@chapter Coding Standards
+@cindex coding standards
+
+@section @value{GDBN} C Coding Standards
+
+@value{GDBN} follows the GNU coding standards, as described in
+@file{etc/standards.texi}.  This file is also available for anonymous
+FTP from GNU archive sites.  @value{GDBN} takes a strict interpretation
+of the standard; in general, when the GNU standard recommends a practice
+but does not require it, @value{GDBN} requires it.
+
+@value{GDBN} follows an additional set of coding standards specific to
+@value{GDBN}, as described in the following sections.
+
+@subsection ISO C
+
+@value{GDBN} assumes an ISO/IEC 9899:1990 (a.k.a.@: ISO C90) compliant
+compiler.
+
+@value{GDBN} does not assume an ISO C or POSIX compliant C library.
+
 @subsection Formatting
 
 @cindex source code formatting
@@ -6208,7 +6369,6 @@ protected with parentheses.)
 Declarations like @samp{struct foo *} should be used in preference to
 declarations like @samp{typedef struct foo @{ @dots{} @} *foo_ptr}.
 
-
 @subsection Function Prototypes
 @cindex function prototypes
 
@@ -6225,30 +6385,6 @@ visible to random source files.
 Where a source file needs a forward declaration of a static function,
 that declaration must appear in a block near the top of the source file.
 
-
-@subsection Internal Error Recovery
-
-During its execution, @value{GDBN} can encounter two types of errors.
-User errors and internal errors.  User errors include not only a user
-entering an incorrect command but also problems arising from corrupt
-object files and system errors when interacting with the target.
-Internal errors include situations where @value{GDBN} has detected, at
-run time, a corrupt or erroneous situation.
-
-When reporting an internal error, @value{GDBN} uses
-@code{internal_error} and @code{gdb_assert}.
-
-@value{GDBN} must not call @code{abort} or @code{assert}.
-
-@emph{Pragmatics: There is no @code{internal_warning} function.  Either
-the code detected a user error, recovered from it and issued a
-@code{warning} or the code failed to correctly recover from the user
-error and issued an @code{internal_error}.}
-
-@subsection Command Names
-
-GDB U/I commands are written @samp{foo-bar}, not @samp{foo_bar}.
-
 @subsection File Names
 
 Any file used when building the core of @value{GDBN} must be in lower
@@ -6278,7 +6414,6 @@ programs, e.g.@: @value{GDBN} and @sc{gd
 
 For other files @samp{-} is used as the separator.
 
-
 @subsection Include Files
 
 A @file{.c} file should include @file{defs.h} first.
@@ -6313,141 +6448,31 @@ header body
 #endif
 @end smallexample
 
+@section @value{GDBN} Python Coding Standards
 
-@subsection Clean Design and Portable Implementation
-
-@cindex design
-In addition to getting the syntax right, there's the little question of
-semantics.  Some things are done in certain ways in @value{GDBN} because long
-experience has shown that the more obvious ways caused various kinds of
-trouble.
-
-@cindex assumptions about targets
-You can't assume the byte order of anything that comes from a target
-(including @var{value}s, object files, and instructions).  Such things
-must be byte-swapped using @code{SWAP_TARGET_AND_HOST} in
-@value{GDBN}, or one of the swap routines defined in @file{bfd.h},
-such as @code{bfd_get_32}.
-
-You can't assume that you know what interface is being used to talk to
-the target system.  All references to the target must go through the
-current @code{target_ops} vector.
-
-You can't assume that the host and target machines are the same machine
-(except in the ``native'' support modules).  In particular, you can't
-assume that the target machine's header files will be available on the
-host machine.  Target code must bring along its own header files --
-written from scratch or explicitly donated by their owner, to avoid
-copyright problems.
-
-@cindex portability
-Insertion of new @code{#ifdef}'s will be frowned upon.  It's much better
-to write the code portably than to conditionalize it for various
-systems.
-
-@cindex system dependencies
-New @code{#ifdef}'s which test for specific compilers or manufacturers
-or operating systems are unacceptable.  All @code{#ifdef}'s should test
-for features.  The information about which configurations contain which
-features should be segregated into the configuration files.  Experience
-has proven far too often that a feature unique to one particular system
-often creeps into other systems; and that a conditional based on some
-predefined macro for your current system will become worthless over
-time, as new versions of your system come out that behave differently
-with regard to this feature.
-
-Adding code that handles specific architectures, operating systems,
-target interfaces, or hosts, is not acceptable in generic code.
-
-@cindex portable file name handling
-@cindex file names, portability
-One particularly notorious area where system dependencies tend to
-creep in is handling of file names.  The mainline @value{GDBN} code
-assumes Posix semantics of file names: absolute file names begin with
-a forward slash @file{/}, slashes are used to separate leading
-directories, case-sensitive file names.  These assumptions are not
-necessarily true on non-Posix systems such as MS-Windows.  To avoid
-system-dependent code where you need to take apart or construct a file
-name, use the following portable macros:
-
-@table @code
-@findex HAVE_DOS_BASED_FILE_SYSTEM
-@item HAVE_DOS_BASED_FILE_SYSTEM
-This preprocessing symbol is defined to a non-zero value on hosts
-whose filesystems belong to the MS-DOS/MS-Windows family.  Use this
-symbol to write conditional code which should only be compiled for
-such hosts.
-
-@findex IS_DIR_SEPARATOR
-@item IS_DIR_SEPARATOR (@var{c})
-Evaluates to a non-zero value if @var{c} is a directory separator
-character.  On Unix and GNU/Linux systems, only a slash @file{/} is
-such a character, but on Windows, both @file{/} and @file{\} will
-pass.
-
-@findex IS_ABSOLUTE_PATH
-@item IS_ABSOLUTE_PATH (@var{file})
-Evaluates to a non-zero value if @var{file} is an absolute file name.
-For Unix and GNU/Linux hosts, a name which begins with a slash
-@file{/} is absolute.  On DOS and Windows, @file{d:/foo} and
-@file{x:\bar} are also absolute file names.
-
-@findex FILENAME_CMP
-@item FILENAME_CMP (@var{f1}, @var{f2})
-Calls a function which compares file names @var{f1} and @var{f2} as
-appropriate for the underlying host filesystem.  For Posix systems,
-this simply calls @code{strcmp}; on case-insensitive filesystems it
-will call @code{strcasecmp} instead.
+@value{GDBN} follows the published @code{Python} coding standards in
+@code{PEP008}.
+See @uref{http://www.python.org/dev/peps/pep-0008/, PEP008}.
 
-@findex DIRNAME_SEPARATOR
-@item DIRNAME_SEPARATOR
-Evaluates to a character which separates directories in
-@code{PATH}-style lists, typically held in environment variables.
-This character is @samp{:} on Unix, @samp{;} on DOS and Windows.
+In addition, the Google standards are also followed where they do not
+conflict with @code{PEP008}.
+See @uref{http://google-styleguide.googlecode.com/svn/trunk/pyguide.html,
+Google Python Style Guide}.
 
-@findex SLASH_STRING
-@item SLASH_STRING
-This evaluates to a constant string you should use to produce an
-absolute filename from leading directories and the file's basename.
-@code{SLASH_STRING} is @code{"/"} on most systems, but might be
-@code{"\\"} for some Windows-based ports.
-@end table
+@subsection @value{GDBN}-specific exceptions
 
-In addition to using these macros, be sure to use portable library
-functions whenever possible.  For example, to extract a directory or a
-basename part from a file name, use the @code{dirname} and
-@code{basename} library functions (available in @code{libiberty} for
-platforms which don't provide them), instead of searching for a slash
-with @code{strrchr}.
+There are a few exceptions to the published standards.
+They exist mainly for consistency with the @code{C} standards.
 
-Another way to generalize @value{GDBN} along a particular interface is with an
-attribute struct.  For example, @value{GDBN} has been generalized to handle
-multiple kinds of remote interfaces---not by @code{#ifdef}s everywhere, but
-by defining the @code{target_ops} structure and having a current target (as
-well as a stack of targets below it, for memory references).  Whenever
-something needs to be done that depends on which remote interface we are
-using, a flag in the current target_ops structure is tested (e.g.,
-@code{target_has_stack}), or a function is called through a pointer in the
-current target_ops structure.  In this way, when a new remote interface
-is added, only one module needs to be touched---the one that actually
-implements the new remote interface.  Other examples of
-attribute-structs are BFD access to multiple kinds of object file
-formats, or @value{GDBN}'s access to multiple source languages.
+@c It is expected that there are a few more exceptions,
+@c so we use itemize here.
 
-Please avoid duplicating code.  For example, in @value{GDBN} 3.x all
-the code interfacing between @code{ptrace} and the rest of
-@value{GDBN} was duplicated in @file{*-dep.c}, and so changing
-something was very painful.  In @value{GDBN} 4.x, these have all been
-consolidated into @file{infptrace.c}.  @file{infptrace.c} can deal
-with variations between systems the same way any system-independent
-file would (hooks, @code{#if defined}, etc.), and machines which are
-radically different don't need to use @file{infptrace.c} at all.
+@itemize @bullet
 
-All debugging code must be controllable using the @samp{set debug
-@var{module}} command.  Do not use @code{printf} to print trace
-messages.  Use @code{fprintf_unfiltered(gdb_stdlog, ...}.  Do not use
-@code{#ifdef DEBUG}.
+@item
+Use @code{FIXME} instead of @code{TODO}.
 
+@end itemize
 
 @node Porting GDB
 


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]