---[  Phrack Magazine   Volume 8, Issue 52 January 26, 1998, article 01 of 20


-------------------------[  P H R A C K     5 2     I N D E X


--------[  Choose your own $PATH adventure



    Whew.  You would be quite surprised at the evil wheels I had to set in
motion in order to get this issue out.  According to Newton, a Phrack Issue
remains at rest or continues to move in a straight line with a uniform
velocity if there is no unbalanced force acting on it.  This issue was at rest.
Its velocity was constant.  And there were few forces acting on it.  Anyhow,
after many machinations it's here.  Enjoy.

    I have a gripe.  Something upon which I'd like dwell for a spell.  Let's
talk about coding aesthetic (from the C programming standpoint).  Now, this is
not a harangue about effective coding or efficient coding, I'll save those for
some other time (perhaps for the time when I feel I can write effective and
efficient code proficiently enough to vituperate to those who do not).  I
want to touch down on a few topics of visual appeal, which are overlooked so
often.

    The five major areas I will cover are indentation, brace placement,
use of whitespace, commenting, as well as variable and function nomenclature.
I suppose I should also mention that coding style is a personal preference
type of thing.  There are all kinds of schools of thought out there, and all
kinds of methodologies on how to write pretty code.  In the grand scheme of
things, none are really any more correct than any others, except mine.

    C is, for the most part, a format free programming language.  Code can be
written with all manner of whitespace, tabs, and newlines.  The compiler
certainly doesn't care.  The machine doesn't care.  This can be a double
edged sword.  There is quite a bit of room for artistic interpretation.  And
just like in real life, there is a lot of crappy art out there.

    Indenting your code is a must.  Please, do this.  Indentation is here for
one simple reason: to clearly and unequivocally define blocks of control.
However, 8 space tabstops are overkill.  Unless you are using a 2 point font on
a 13" screen, 4 spaces should easily define your control blocks.  This allows
you to maintain clarity on an 80 column screen while nesting blocks of control
much deeper then you would with 8 space tab stops.  2 space tabstop advocates
should be shot.  However, don't let typography take over your code (ala ink
obscuring the intent).  If you have 7 million levels of indentation, perhaps
you should rethink your approach to tackling the problem...

    Bracing has a simple solution.  The most effective use of bracing is in
placing them on newlines so that they neatly enclose the area of control.  This
is especially important with nested levels of control.  I know this generates
empty lines.  Oh well.  They're free.  Blocks of control become easily visible
and it is easy to isolate one from another.  This goes for functions as well
as conditionals and loop structures.  I know I go against K&R here.  Oh well.

    In the pursuit of clear, readable code, whitespace is your friend.  Single
space all keywords and all variables and constants separated by commas.  It's
a simple thing to do to drastically improve readability.  When you have a
series of assignments, one after another, it's a nice touch to line them up on
the closest relative 4 space boundary.  And please, no spaces between structure
pointer operators and structure contents.

    Commenting is a delicate matter.  Descriptive, concise, well written code
shouldn't really need commenting, or at least very much of it.  But this isn't
a rant about descriptive, concise, well written code.  If you feel the need
to comment your code, follow a few simple rules:
    - Keep the comment block as small as possible.
    - Don't tab out your comment frames to line up with each other.  That's
      just plain fucking annoying.  If you're doing that, you have too many
      comments anyway.
    - Commenting datatype declarations rather then the functions that
      manipulate them is usually more helpful.
    - If you must comment, keep your style as consistent as possible.  If the
      commenting detracts from the readibilty of your code, you've just ponied
      up any clarification you might have achieved with the commenting.

    The major exception to these rules are file headers.  The beginning of
source and header files should always have some descriptive information,
including: file name, author, purpose, modification dates, etc...  These
comment blocks should always have a simple vertical line of unobtrusive
astricks, framed with the required forward slashes.  People using C++ style
commenting in C programs should be drawn and quartered.

    The other exception to this rule is when you are writing code specifically
for the benefit of others.  If the code is intended to be a learning tool, 
copious commenting is allowable.

    Variable and function nomenclature should have connotation as to what their
purpose in life is.  As short as possible while still preserving some sort of
identity.  Descriptive names are wonderful, but don't go overboard.  Generally,
a condensed one or two word descriptor (possiblely connected via an underscore)
will work fine.  And please, no mixed case.  The only time uppercase characters
should appear in C code are in symbolic constants and macros (and possibly
strings and comments).


    This tirade is the result of my experiences in reading and writing C code.
In my travels as a stalwart mediocre programmer, I have progressed through many
levels of maturity in my programming style.  Much of my old code exhibits many
of the very things eschewed as anathema in this jeremiad.  Well, what can I
say?  I believe that I have grown.  I am at home with the me.  This is me
breathing.  (Tell me what movie that's from, and I will give you a Phrack
Donut.)


Enjoy the magazine.  It is by and for the hacking community.  Period.


-- Editor in Chief ----------------[  route
-- Director of Public Operations --[  dangergirl
-- Phrack World News --------------[  disorder
-- Werdsmith ----------------------[  loadammo
-------- Elite -------------------->  asriel
-- Santa vs. Jesus ----------------[  ISS vs. SNI
-- Festively Plump ----------------[  Cartman
-- Extra Special Thanks -----------[  No one.
-- Official Phrack CD -------------[  FLA/Flavour of the Weak
-- Official Phrack Drink ----------[  `The C Kilborn` (2.9 parts ketel one,
-----------------------------------|  .1 parts tonic)
-- Shout Outs and Thank Yous ------[  Lords of Acid, cantor, Yggdrasil,
-----------------------------------|  snokerash, Voyager, TNO, Jeff Thompson,
-----------------------------------|  angstrom, redragon, Rob Pike, halflife
-- B.A. Baracus Phrack Fracas -----[  loadammo vs. Death Veggie
-- Original flip.c author (props) -[  datagram
-- Gas Face Given (drops) ---------[  solo, klepto

Phrack Magazine V. 8, #52, January 26, 1998.  ISSN 1068-1035
Contents Copyright (c) 1998 Phrack Magazine. All Rights Reserved.  Nothing
may be reproduced in whole or in part without written permission from the
editor in chief.  Phrack Magazine is made available quarterly to the public,
free of charge.  Go nuts people.


Subscription requests, articles, comments, whatever should be directed to:

                phrackedit@phrack.com

Submissions to the above email address may be encrypted with the following key:

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2

mQENAzMgU6YAAAEH/1/Kc1KrcUIyL5RBEVeD82JM9skWn60HBzy25FvR6QRYF8uW
ibPDuf3ecgGezQHM0/bDuQfxeOXDihqXQNZzXf02RuS/Au0yiILKqGGfqxxP88/O
vgEDrxu4vKpHBMYTE/Gh6u8QtcqfPYkrfFzJADzPEnPI7zw7ACAnXM5F+8+elt2j
0njg68iA8ms7W5f0AOcRXEXfCznxVTk470JAIsx76+2aPs9mpIFOB2f8u7xPKg+W
DDJ2wTS1vXzPsmsGJt1UypmitKBQYvJrrsLtTQ9FRavflvCpCWKiwCGIngIKt3yG
/v/uQb3qagZ3kiYr3nUJ+ULklSwej+lrReIdqYEABRG0GjxwaHJhY2tlZGl0QGlu
Zm9uZXh1cy5jb20+tA9QaHJhY2sgTWFnYXppbmU=
=1iyt
-----END PGP PUBLIC KEY BLOCK-----
                   
As always, ENCRYPTED SUBSCRIPTION REQUESTS WILL BE IGNORED.  Phrack goes out 
plaintext.  You certainly can subscribe in plaintext.

phrack:~# head -20 /usr/include/std-disclaimer.h
/*
 *  All information in Phrack Magazine is, to the best of the ability of the 
 *  editors and contributors, truthful and accurate.  When possible, all facts
 *  are checked, all code is compiled.  However, we are not omniscient (hell,
 *  we don't even get paid).  It is entirely possible something contained 
 *  within this publication is incorrect in some way.  If this is the case, 
 *  please drop us some email so that we can correct it in a future issue.  
 *
 *
 *  Also, keep in mind that Phrack Magazine accepts no responsibility for the
 *  entirely stupid (or illegal) things people may do with the information
 *  contained here-in.  Phrack is a compendium of knowledge, wisdom, wit, and
 *  sass.  We neither advocate, condone nor participate in any sort of illicit 
 *  behavior.  But we will sit back and watch.
 *
 *
 *  Lastly, it bears mentioning that the opinions that may be expressed in the
 *  article of Phrack Magazine are intellectual property of their authors.
 *  These opinions do not necessarily represent those of the Phrack Staff.
 */

-------------------------[  T A B L E   O F   C O N T E N T S

 1 Introduction                                            Phrack Staff   12K
 2 Phrack Loopback                                         Phrack Staff   60K
 3 Line Noise                                              various        79K 
 4 Phrack Prophile on o0                                   Phrack Staff   07K
 5 Everything a hacker needs to know about getting busted  Agent Steal    72K
 6 Hardening the Linux Kernel                              daemon9        42K
 7 The Linux pingd                                         daemon9        17K
 8 Steganography Thumbprinting                             anonymous      35K
 9 On the Morality of Phreaking                            Phrack Staff   19K
10 A Quick NT Interrogation Probe                          twitch         18K
11 Subscriber Loop Carrier                                 voyager        48K
12 Voice Response Systems                                  voyager        18K
13 Pay Per View (you don't have to)                        cavalier       19K
14 The International Crime Syndicate Association           D. Demming     20K
15 Digital Certificates                                    Yggdrasil      14K
16 Piercing Firewalls                                      bishnu         31K
17 Protected mode programming and O/S development          mythrandir     76K
18 Weakening the Linux Kernel                              plaguez        27K
19 Phrack World News                                       Disorder       64K
20 extract.c                                               Phrack Staff   08K

                                                                         687K

-----------------------------------------------------------------------------

    When Sen. Bob Kerrey (D-Neb.) was asked to define encryption, the results 
were horrific.  "Well, I mean, to answer your question, I mean, encryption is 
-- the political equivalent of encryption is you ask me a question, I give you
an answer and you don't understand it," he managed. "I mean, I intentionally 
garble the answer frequently.  I intentionally garble the response so that you 
can't understand what I'm saying.  And that's -- you notice that I've got the
ability to do that." 

-----------------------------------------------------------------------------

----[  EOF