Squid Web Cache wiki

Squid Web Cache documentation

🔗 Code style guidelines

:information_source: details labeled ENFORCED are checked and forced by source testing mechanisms.

🔗 C++ Guidelines

🔗 Source formatting guidelines

🔗 ENFORCED rules

:warning: The formater is known to enforce some weird indentation at times. Notably after #if ... #endif directives. If you find these, please ignore for now. They will be corrected in a later version of the formater.

🔗 Mandatory coding rules

🔗 Suggested coding rules

🔗 Word capitalization example

namespace Foo // namespace name CamelCased
{

class ClassStats; // class type name CamelCased

class ClassName
{
public:
  static ClassStats &Stats(); // static methods use CameCased

  void clear();

private:
  static ClassStats Stats_; // static member CamelCased. Underscore since name collides with Stats() method

  int internalState;
};

extern void ReportUsage(ostream &); // global function CamelCased

🔗 Class declaration layout

class Foo : public Bar
{
  CBDATA_* or MEMPROXY_* special macro.

public:
  all public typedef

  all constructors and operators
  Foo destructor (if any)

  /* Bar API */
  all methods overloaded from FooBar parent class

  all public static methods
  all public member methods

  all public static variables
  all public member variables

protected:
  all protected static methods
  all protected member methods

  all protected static variables
  all protected member variables

private:
  all private static methods
  all private member methods

  all private static variables
  all private member variables
};

🔗 Member naming

Pick one of the applicable styles described below and stick to it. For old classes, try to pick the style which is closer to the style being used.

  1. Accessors
    Explicit set, get, has :
    void setMember(const Member &);
    const Member &getMember() const; // may also return a copy
    Member &getMember();
    bool hasMember() const;
    

    OR Compact:

    void member(const Member &);
    const Member &member() const; // may also return a copy
    Member &member();
    bool hasMember() const;
    
  2. Data members
    For public data members, do not use underscore suffix. Use verb prefixes for boolean members.
     int counter;
     int next;
     bool isClean;
     bool sawHeader;
    
    For protected and private data members: May use underscore suffix to emphasize that the data member is not public and must use underscore suffix if the data member name would otherwise clash with a method name. Use verb prefixes for boolean members.
     int counter_;
     int next_;
     bool isClean_;
     bool sawHeader_;
    
  3. State checks
    • prefixed with an appropriate verb: is, has/have, can
         bool canVerb() const;
         bool hasNoun() const;
         bool haveNoun() const; // if class name is plural
         bool isAdjective() const; // but see below
      
    • Avoid negative words because double negation in if-statements will be confusing; let the caller negate when needed.
         bool notAdjective() const; // XXX: avoid due to !notAdjective()
      
    • The verb is may be omitted, especially if the result cannot be confused with a command: the confusion happens if the adjective after is can be interpreted as a verb
       bool isAtEnd() const; // OK, but excessive
       bool atEnd() const; // OK, no confusion
    
       bool isFull() const;  // OK, but excessive
       bool full() const;  // OK, no confusion
    
       bool clear() const; // XXX: may look like a command to clear state
       bool empty() const; // XXX: may look like a "become empty" command
    

🔗 File #include guidelines

  1. minimal system includes
  2. custom headers provided by Squid:
    • place internal header includes above system includes
    • omit wrappers
    • always include with double-quotes (“”)
    • ENFORCED: sort alphabetically
    • use full path (only src/ prefix may be omitted)
  3. system C++ headers (without any extension suffix):
    • always include with <>
    • omit any HAVE_ wrapper
    • sort alphabetically
    • if the file is not portable, do not use it
  4. system C headers (with a .h suffix):
    • always include with <>
    • mandatory HAVE_FOO_H wrapper
    • avoid where C++ alternative is available
    • sort alphabetically
    • should import order-dependent headers through libcompat

ENFORCED

.cc files only:

.h and .cci files

Layout Example:

// local includes sorted alphabetically with squid.h first
#include "squid.h"
#include "comm/forward.h"
#include "local.h"

// system C++ includes alphabetically sorted and not-wrapped
#include <cstdlib>
#include <iostream>

// System C includes alphabetically sorted and wrapped
#if HAVE_ACCESS_H
#include <access.h>
#endif
#if HAVE_GETOPT_H
#include <getopt.h>
#endif

🔗 Component Macros in C++

Squid uses autoconf defined macros to eliminate experimental or optional components at build time.

ENFORCED:

🔗 See Also

Navigation: Site Search, Site Pages, Categories, 🔼 go up