标签 C 下的文章

Hello, Cocos2d-x

女儿从两岁半开始接触iPad,在这个年龄段也只有一些幼教类游戏适合她玩。虽然知道iPad玩久了对视力有伤害,但有时候还真拗不过果果,索性 也就让她玩一会儿。之前对智能终端上的东西不是很在意,也没啥兴趣,这大概与当年在大学时做Win32 GUI开发的糟糕经历多多少少有点关系。不过智能终端是大势所趋,历史的潮流不能违抗。虽然自己并非以Android/iOS编程为主业,但适当学习学习 总归没有坏处,万一作出一个像"Flappy Bird"的游戏,爆发一下,还是蛮Happy的。于是在开始学习实践之前给自己定了一个小目标:今年六一儿童节送给女儿一款自己制作的小游戏。

智能终端上的游戏目前风头正劲,试问哪个智能手机上没有几款企鹅公司出品的游戏呢!之前从未涉猎过游戏开发,但知道游戏开发前要挑选一款合适的游 戏引擎,自己从头开始敲代码的时代已经out了。在寻觅游戏引擎之前,我需要回答三道摆在我面前的选择题:

    1、2D引擎还是3D引擎?
    2、平台专用引擎还是跨平台引擎?
    3、收费引擎还是开源引擎?

作为入门级选手,2D游戏显然更适合上手一些,另外适合果果这个年龄段的幼教类的游戏也多以2D游戏居多。3D游戏本身也太难了,不仅要 Programming能力,还要3D建模能力,这些学习起来周期就太长了;一直是Ubuntu Fans,手头没有Mac Book,这样开发iOS程序变成一件糟心的事,在Ubuntu下搭建iOS App开发环境繁杂的很,即便是虚拟机也懒得尝试。但从游戏体验来看,还是在iPad上玩更好一些,因此最好引擎能跨平台,以便后续迁移到iOS上;开源 和用开源惯了,收费的引擎目前不在考虑范围之内。综上,我要寻找的是一款开源的、跨平台的Mobile 2D Game Engine。

于是我找到了Cocos2d-x!Cocos2d-x是Cocos2d-iphone的C++跨平台分支,由于是国人创立的,在国内有着较大的用 户群,引擎资料也较多,社区十分活跃。国内已经出版了多本有关Cocos2d-x的中文书籍,比如《Cocos2d-x高级开发教程:制作自己的 “捕鱼达人”》 、《Cocos2d-x权威指南》 等都还不错。更重要的是Cocos2d-x自带了丰富的例子,供初学者“临摹学习”,其中cocos2d-x-2.2.2/samples/Cpp /TestCpp这个例子几乎涵盖了该引擎的绝大多数功能。下面就开启Cocos2d-x的入门之旅(For Android)。

一、引擎安装

试验环境:
   Ubuntu 12.04.1 x86_64
   gcc 4.6.3
   javac 1.7.0_21
   java "1.7.0_21" HotSpot 64-bit Server VM
   adt-bundle-linux-x86_64-20131030.zip
   android-ndk-r9d-linux-x86_64.tar.bz2

Cocos2d-x官网目前提供2.2.2稳定版以及3.0beta2版的下载(当然你也可以下载到更老的版本)。由于3.0改变较大,资料不 多,且对编译器等版本的要求较高(需要支持C++ 11标准),因此这里依旧以2.2.2版本作为学习目标。Cocos2d-x-2.2.2下载后解压到某个目录:比如/home1/tonybai/android-dev/cocos2d-x-2.2.2。 如果仅是用Cocos2d-x开发Android版本游戏,则不需要做什么编译工作。Android Game Project会在Project build时自动用NDK的编译器编译C++代码,并与NDK链接。如果你想早点看看Cocos2d-x sample中的例子运行起来到底是什么样子的,你可以在Ubuntu下编译出Linux版本的游戏:在cocos2d-x-2.2.2下执行make-all-linux-project.sh即可。编译需要一段时间,编译成 功后,我们可以进入到“cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.linux/bin/release” 下执行“HelloCpp”这个可执行文件,一个最简单的Cocos2d-x游戏就会展现在你的面前了。

Android sample project的构建稍微复杂些:

首先在Eclipse中添加libcocos2dx Library project from existed code(注意:不Copy到workspace,原地建立)。该Project的代码路径为cocos2d-x-2.2.2/cocos2dx/platform /android/java。在project.properties和AndroidManifest.xml适当修改你所使用的api版本, 以让编译通过。我这里用的是 target=android-19。

然后,设置NDK_ROOT环境变量(比如export NDK_ROOT='/home1/tonybai/android-dev/adt-bundle-linux-x86_64/android-ndk-r9c'), 供build_native.sh使用。

最后添加游戏project。在Eclipse中添加HelloCpp project from existed code,位置cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android(注 意:不Copy到Workspace中,原地建立)。在HelloCpp的project.properties中添加“android.library.reference.1=../../../../cocos2dx/platform/android /java”。同样别忘了在project.properties和AndroidManifest.xml适当修改你所使用 的api版本,以让编译通过。

如果一切顺利的话,你会在Console窗口看到“**** Build Finished ****”。Problems窗口显示“0 errors“。 启动Android模拟器,Run Application,同样的HelloCpp画面会呈现在模拟器上。

Cocos2d-x是建构在OpenGL技术之上的。对于Android平台而言,Android SDK已经完全封装了opengl es 1.1/2.0的API(android.opengl.*;javax.microedition.khronos.egl.*;javax.microedition.khronos.opengles.*), 引擎完全可以建立在这个之上,无需C++代码。但Cocos2d-x是一个跨平台的2D游戏引擎,核心选择了用C++代码实现(iOS提供的C绑 定,不提供Java绑定;Android则提供了Java和C绑定),因此 在开发Android平台的2D游戏时,引擎部分是SDK与NDK交相互应,比如GLThread的创建和管理用的是SDK的 GLSurfaceView和GLThread,但真正的Surface绘制部分则是回调Cocos2d-x用C++编写的绘制实现(链接NDK 中的库)。

二、Cocos2d-x Android工程代码组织结构

以samples/Cpp/HelloApp的Android工程为例,Android版的Cocos2d-x工程与普通android应用程序 差别 不大,核心部分只是多了一个jni目录和一个build_native.sh脚本文件。其中jni目录下存放的是Java和C++调用转换的“胶 水”代码;build_native.sh则是用于编译jni下C++代码以及 cocos2dx_static library代码的构建脚本。

HelloCpp的构建过程摘要如下:

**** Build of configuration Default for project HelloCpp ****

bash /home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/build_native.sh
NDK_ROOT = /home1/tonybai/android-dev/adt-bundle-linux-x86_64/android-ndk-r9c
COCOS2DX_ROOT = /home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/../../../..
APP_ROOT = /home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/..
APP_ANDROID_ROOT = /home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android
+ /home1/tonybai/android-dev/adt-bundle-linux-x86_64/android-ndk-r9c/ndk-build -C /home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.androidNDK_MODULE_PATH=/home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/../../../..:/home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/../../../../cocos2dx/platform/third_party/android/prebuilt
Using prebuilt externals
Android NDK: WARNING:/home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/../../../../cocos2dx/Android.mk:cocos2dx_static: LOCAL_LDLIBS is always ignored for static libraries  
make: Entering directory `/home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android'
[armeabi] Compile++ thumb: hellocpp_shared <= main.cpp
[armeabi] Compile++ thumb: hellocpp_shared <= AppDelegate.cpp
[armeabi] Compile++ thumb: hellocpp_shared <= HelloWorldScene.cpp
[armeabi] Compile++ thumb: cocos2dx_static <= CCConfiguration.cpp
[armeabi] Compile++ thumb: cocos2dx_static <= CCScheduler.cpp
 … …
[armeabi] Compile++ thumb: cocos2dx_static <= CCTouch.cpp
[armeabi] StaticLibrary  : libcocos2d.a
[armeabi] Compile thumb  : cpufeatures <= cpu-features.c
[armeabi] StaticLibrary  : libcpufeatures.a
[armeabi] SharedLibrary  : libhellocpp.so
[armeabi] Install        : libhellocpp.so => libs/armeabi/libhellocpp.so
make: Leaving directory `/home1/tonybai/android-dev/cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android'

**** Build Finished ****

指挥NDK编译的则是jni下的Android.mk文件,其角色类似于Makefile。

三、Cocos2d-x Android工程代码阅读

单独将如何阅读代码拿出来,是为了后面分析引擎的驱动流程做准备工作。学习类似Cocos2d-x这样的游戏引擎,仅仅停留在游戏逻辑层代码是不 能很好的把握引擎本质的,因此适当的挖掘引擎实现实际上对于理解和使用 引擎都是大有裨益的。

以一个Cocos2d-x Android工程为例,它的游戏逻辑代码以及涉及的引擎代码涵盖在一下路径下(还是以HelloCpp的Android工程为例):

    项目层:
        * cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/src  主Activity的实现;
        * cocos2d-x-2.2.2/samples/Cpp/HelloCpp/proj.android/jni/hellocpp  Cocos2dxRenderer类的nativeInit实现,用于引出Application的入口;
        * cocos2d-x-2.2.2/samples/Cpp/HelloCpp/Classes 你的游戏逻辑,以C++代码形式呈现;
   
    引擎层:
        * cocos2d-x-2.2.2/cocos2dx/platform/android/java/src 引擎层对Android Activity、GLSurfaceView以及Render的封装
        * cocos2d-x-2.2.2/cocos2dx/platform/android/jni 对应上面封装的native method实现
        * cocos2d-x-2.2.2/cocos2dx、cocos2d-x-2.2.2/cocos2dx/platform、cocos2d-x- 2.2.2/cocos2dx/platform/android   cocos2dx引擎的核心实现(针对android平台)

后续的代码分析也将从这两个层次、六处位置出发。

四、从Activity开始

之前多少了解了一些Android App开发的知识,Android App都是始于Activity的。游戏也是App的一种,因此在Android平台上,Cocos2d-x游戏也是从Activity开始的。于是 Activity,确切的说是Cocos2dxActivity是我们这次引擎驱动机制分析的出发点。

回顾Android Activity的Lifecycle,Activity启动的顺序是:Activity.onCreate -> Activity.onStart() -> Activity.onResume()。接下来我们将按照 这条主线进行引擎驱动机制的分析。

HelloCpp.java中的HelloCpp这个Activity完全无所作为,仅仅是继承其父类Cocos2dxActivity的实现罢 了。

// HelloCpp.java
public class HelloCpp extends Cocos2dxActivity{
    protected void onCreate(Bundle savedInstanceState){
        super.onCreate(savedInstanceState);
    }
    … …
}

我们来看Cocos2dxActivity类。

// Cocos2dxActivity.java

@Override
protected void onCreate(final Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    sContext = this;
    this.mHandler = new Cocos2dxHandler(this);
    this.init();
    Cocos2dxHelper.init(this, this);

public void init() {
        // FrameLayout
        ViewGroup.LayoutParams framelayout_params =
            new ViewGroup.LayoutParams(ViewGroup.LayoutParams.FILL_PARENT,
                                       ViewGroup.LayoutParams.FILL_PARENT);
        FrameLayout framelayout = new FrameLayout(this);
        framelayout.setLayoutParams(framelayout_params);

        … …
        // Cocos2dxGLSurfaceView
        this.mGLSurfaceView = this.onCreateView();

        // …add to FrameLayout
        framelayout.addView(this.mGLSurfaceView);
        … …
        this.mGLSurfaceView.setCocos2dxRenderer(new Cocos2dxRenderer());
        … …

        // Set framelayout as the content view
        setContentView(framelayout);
}

从上面代码可以看出,onCreate调用的init方法才是Cocos2dxActivity初始化的核心。在init方法 中,Cocos2dxActivity创建了一个Framelayout实例,并将该实例作为content View赋给了Cocos2dxActivity的实例。Framelayout实例也并不孤单,一个设置了Cocos2dxRenderer实例的 GLSurfaceView被Added to it。而Cocos2d-x引擎的初始化已经悄悄地在这几行代码间完成了,至于初始化的细节我们后续再做分析。

接下来是onResume方法,它的实现如下:

    @Override
    protected void onResume() {
        super.onResume();

        Cocos2dxHelper.onResume();
        this.mGLSurfaceView.onResume();
    }

onResume调用了View的onResume()。

// Cocos2dxGLSurfaceView:
    @Override
    public void onResume() {
        super.onResume();

        this.queueEvent(new Runnable() {
            @Override
            public void run() {
                Cocos2dxGLSurfaceView.this.mCocos2dxRenderer.handleOnResume();
            }
        });
    }

Cocos2dxGLSurfaceView将该事件打包放到队列里,扔给了另外一个线程去执行(后续会详细说明这个线程),对应的方法在 Cocos2dxRenderer class中。

    public void handleOnResume() {
        Cocos2dxRenderer.nativeOnResume();
    }

Render实际上调用的是native方法。

    JNIEXPORT void JNICALL Java_org_cocos2dx_lib_Cocos2dxRenderer_nativeOnResume() {
        if (CCDirector::sharedDirector()->getOpenGLView()) {
            CCApplication::sharedApplication()->applicationWillEnterForeground();
        }
    }

applicationWillEnterForeground方法在你的AppDelegate.cpp中;

void AppDelegate::applicationWillEnterForeground() {
    CCDirector::sharedDirector()->startAnimation();//

    // if you use SimpleAudioEngine, it must resume here
    // SimpleAudioEngine::sharedEngine()->resumeBackgroundMusic();
}

这里仅是重新获得了一下时间罢了。

五、Render Thread(渲染线程) - GLThread

游戏引擎要兼顾UI事件和屏幕帧刷新。Android的OpenGL应用采用了UI线程(Main Thread) +  渲染线程(Render Thread)的模式。Activity活在Main Thread(主线程)中,也叫做UI线程。该线程负责捕获与用户交互的信息和事件,并与渲染(Render)线程交互。比如当用户接听电话、切换到其他 程序时,渲染线程必须知道发生了 这些事件,并作出即时的处理,而这些事件及处理方式都是由主线程中的Activity以及其装载的View传递给渲染线程的。我们在Cocos2dx的框 架代码中看不到渲染线程的诞生过程,这是因为这一过程是在Android SDK层实现的。

我们回顾一下Cocos2dxActivity.init方法的关键代码:

    // Cocos2dxGLSurfaceView
    this.mGLSurfaceView = this.onCreateView();

    // …add to FrameLayout
    framelayout.addView(this.mGLSurfaceView);
    this.mGLSurfaceView.setCocos2dxRenderer(new Cocos2dxRenderer());
       
    // Set framelayout as the content view
    setContentView(framelayout);

Cocos2dxGLSurfaceView是 android.opengl.GLSurfaceView的子类。在android 上做原生opengl es 2.0编程的人应该都清楚GLSurfaceView的重要性。但渲染线程并非是在Cocos2dxGLSurfaceView实例化时被创建的,而是在 setRenderer的时候。

我们来看Cocos2dxGLSurfaceView.setCocos2dxRenderer的实现:

    public void setCocos2dxRenderer(final Cocos2dxRenderer renderer) {
        this.mCocos2dxRenderer = renderer;
        this.setRenderer(this.mCocos2dxRenderer);
    }

setRender是Cocos2dxGLSurfaceView父类GLSurfaceView实现的方法。在Android SDK GLSurfaceView.java文件中,我们看到:

       public void setRenderer(Renderer renderer) {
        checkRenderThreadState();
        if (mEGLConfigChooser == null) {
            mEGLConfigChooser = new SimpleEGLConfigChooser(true);
        }
        if (mEGLContextFactory == null) {
            mEGLContextFactory = new DefaultContextFactory();
        }
        if (mEGLWindowSurfaceFactory == null) {
            mEGLWindowSurfaceFactory = new DefaultWindowSurfaceFactory();
        }
        mRenderer = renderer;
        mGLThread = new GLThread(mThisWeakRef);
        mGLThread.start();

    }

GLThread的实例是在这里被创建并开始执行的。至于渲染线程都干了些什么,我们可以通过其run方法看到:

        @Override
        public void run() {
            setName("GLThread " + getId());
            if (LOG_THREADS) {
                Log.i("GLThread", "starting tid=" + getId());
            }

            try {
                guardedRun();
            } catch (InterruptedException e) {
                // fall thru and exit normally
            } finally {
                sGLThreadManager.threadExiting(this);
            }
        }

run方法并没有给我们带来太多有价值的东西,真正有价值的信息藏在guardedRun方法中。guardedRun是这个源文件中规模最为庞 大的方法,但抽取其核心结构后,我们发现它大致就是一个死循环,以下是摘要式的伪代码:

while (true) {
   synchronized (sGLThreadManager) {
       while (true) {
           …. …
           if (! mEventQueue.isEmpty()) {
               event = mEventQueue.remove(0);
               break;
           }
        }  
   }//end of synchronized (sGLThreadManager)

    if (event != null) {
       event.run();
       event = null;
       continue;
   }  

   if needed
       view.mRenderer.onSurfaceCreated(gl, mEglHelper.mEglConfig);

   if needed
       view.mRenderer.onSurfaceChanged(gl, w, h);

   if needed
       view.mRenderer.onDrawFrame(gl);
}

在这里我们看到了event、Renderer的三个回调方法onSurfaceCreated、onSurfaceChanged以及 onDrawFrame,后续我们会对这三个函数做详细分析的。

六、游戏逻辑的入口

在HelloCpp的Classes下有好多C++代码文件(涉及具体的游戏逻辑),在HelloCpp的android project jni目录下也有Jni胶水代码,那么这些代码是如何和引擎一起互动生效的呢?

上面讲到过,涉及到画面的一些渲染都是在GLThread中进行的,这涉及到onSurfaceCreated、 onSurfaceChanged以及onDrawFrame三个方法。我们看看 Cocos2dxRenderer.onSurfaceCreated方法的实现,该方法会在Surface被首次渲染时调用:

    public void onSurfaceCreated(final GL10 pGL10, final EGLConfig pEGLConfig) {
        Cocos2dxRenderer.nativeInit(this.mScreenWidth, this.mScreenHeight);
        this.mLastTickInNanoSeconds = System.nanoTime();
    }

该方法继续调用HelloCpp工程jni目录下的nativeInit代码:

void Java_org_cocos2dx_lib_Cocos2dxRenderer_nativeInit(JNIEnv*  env, jobject thiz, jint w, jint h)
{
    if (!CCDirector::sharedDirector()->getOpenGLView())
    {
        CCEGLView *view = CCEGLView::sharedOpenGLView();
        view->setFrameSize(w, h);

        AppDelegate *pAppDelegate = new AppDelegate();
        CCApplication::sharedApplication()->run();
    }
    else
    {
        ccGLInvalidateStateCache();
        CCShaderCache::sharedShaderCache()->reloadDefaultShaders();
        ccDrawInit();
        CCTextureCache::reloadAllTextures();
        CCNotificationCenter::sharedNotificationCenter()->postNotification(EVENT_COME_TO_FOREGROUND, NULL);
        CCDirector::sharedDirector()->setGLDefaultValues();
    }
}

这似乎让我们看到了游戏逻辑的入口了:

    CCEGLView *view = CCEGLView::sharedOpenGLView();
    view->setFrameSize(w, h);

    AppDelegate *pAppDelegate = new AppDelegate();
    CCApplication::sharedApplication()->run();

继续追踪CCApplication::run方法:

int CCApplication::run()
{
    // Initialize instance and cocos2d.
    if (! applicationDidFinishLaunching())
    {
        return 0;
    }

    return -1;
}

applicationDidFinishLaunching,没错这就是游戏逻辑的入口了。我们得回到Samples代码目录中去找到对应方法 的实现。

//cocos2d-x-2.2.2/samples/Cpp/HelloCpp/Classes/AppDelegate.cpp

bool AppDelegate::applicationDidFinishLaunching() {
    // initialize director
    CCDirector* pDirector = CCDirector::sharedDirector();
    CCEGLView* pEGLView = CCEGLView::sharedOpenGLView();

    pDirector->setOpenGLView(pEGLView);
    CCSize frameSize = pEGLView->getFrameSize();
    … …

    // turn on display FPS
    pDirector->setDisplayStats(true);

    // set FPS. the default value is 1.0/60 if you don't call this
    pDirector->setAnimationInterval(1.0 / 60);

    // create a scene. it's an autorelease object
    CCScene *pScene = HelloWorld::scene();

    // run
    pDirector->runWithScene(pScene);

    return true;
}

的确,在applicationDidFinishLaunching中我们做了很多引擎参 数的设置。接下来大管家CCDirector实例登场,并运行了HelloWorld Scene的实例。但这依旧是初始化的一部分,虽然方法名让人听起来像是某种持续连贯行为:

//cocos2d-x-2.2.2/cocos2dx/CCDirector.cpp

void CCDirector::runWithScene(CCScene *pScene)
{
    … …

    pushScene(pScene);
    startAnimation();
}

void CCDisplayLinkDirector::startAnimation(void)
{
    if (CCTime::gettimeofdayCocos2d(m_pLastUpdate, NULL) != 0)
    {
        CCLOG("cocos2d: DisplayLinkDirector: Error on gettimeofday");
    }

    m_bInvalid = false;
}

两个方法均只是初始化了某些数据成员变量,并未真正将引擎驱动起来。

七、驱动引擎

之所以游戏画面是运动的,那是因为屏幕以较高的帧数刷新的缘故,这样人眼就会看到连续的动作,就和电影的放映原理是一样的。在Cocos2d-x 引擎中这些驱动屏幕刷新的代码在哪里呢?

我们回顾一下之前谈到的GLThread线程,我们说过画面渲染的工作都是由它来完成的。GLThread的核心是guardedRun函数,该 函数以“死循环”的方式调用Cocos2dxRender.onDrawFrame方法对画面进行持续渲染。

我们来看看引擎实现的Cocos2dxRender.onDrawFrame方法:

public void onDrawFrame(final GL10 gl) {
        /*
         * FPS controlling algorithm is not accurate, and it will slow down FPS
         * on some devices. So comment FPS controlling code.
         */

        /*
        final long nowInNanoSeconds = System.nanoTime();
        final long interval = nowInNanoSeconds – this.mLastTickInNanoSeconds;
        */

        // should render a frame when onDrawFrame() is called or there is a
        // "ghost"
        Cocos2dxRenderer.nativeRender();

        /*
        // fps controlling
        if (interval < Cocos2dxRenderer.sAnimationInterval) {
            try {
                // because we render it before, so we should sleep twice time interval
                Thread.sleep((Cocos2dxRenderer.sAnimationInterval – interval) / Cocos2dxRenderer.NANOSECONDSPERMICROSECOND);
            } catch (final Exception e) {
            }
        }

        this.mLastTickInNanoSeconds = nowInNanoSeconds;
        */
    }

这个方法实现得比较奇怪,似乎修改过多次,但最后还是决定只保留了一个方法调用: Cocos2dxRenderer.nativeRender()。从注释掉的代码来看,似乎是想在这个方法中通过Thread.sleep来控制 Render Thread渲染的帧率。但由于控制的不理想,索性就不控制了,让guardedRun真正变成了dead loop。但从HelloCpp Sample运行时的状态显示,画面始终保持在60帧左右,让人十分诧异。据说Cocos2d-x 3.0版本重新设计了渲染这块的机制。(后记:在Android上虽然没有帧数控制,但真正的渲染帧率实际上还受到"垂直同步"信号 – vertical sync的影响。在游戏中,也许强劲的显卡迅速的绘制完一屏的图像,但是没有垂直同步信号的到达,显卡无法绘制下一屏,只有等vsync信号到达,才可以绘制。这样fps实际上要要受到操作系统刷新率值的制约)。

nativeRender从命名来看,这显然是一个C++编写的函数实现。我们只能到jni目录下寻找。

cocos2d-x-2.2.2/cocos2dx/platform/android/jni/ Java_org_cocos2dx_lib_Cocos2dxRenderer.cpp

    JNIEXPORT void JNICALL Java_org_cocos2dx_lib_Cocos2dxRenderer_nativeRender(JNIEnv* env) {
        cocos2d::CCDirector::sharedDirector()->mainLoop();
    }

nativeRender也很简洁,直接调用了CCDirector的mainLoop,也就是说每帧渲染过程中真正干活地是 CCDirector::mainLoop。到此我们终于找到了引擎渲染的驱动器:GLThead::guardedRun,以“死循环”的方式刷新着画面,让我们感受到“动”的魅力。

八、mainLoop

进一步我们来看看mainLoop所做的工作。mainLoop是CCDirector类的一个纯虚函数,CCDirector的子类CCDisplayLinkDirector真正实现了 它:

//CCDirector.cpp
void CCDisplayLinkDirector::mainLoop(void)
{
    if (m_bPurgeDirecotorInNextLoop)
    {
        m_bPurgeDirecotorInNextLoop = false;
        purgeDirector();
    }
    else if (! m_bInvalid)
     {
         drawScene();

         // release the objects
         CCPoolManager::sharedPoolManager()->pop();
     }
}

void CCDirector::drawScene(void)
{
    // calculate "global" dt
    calculateDeltaTime();

    //tick before glClear: issue #533
    if (! m_bPaused)
    {
        m_pScheduler->update(m_fDeltaTime);
    }

    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

    /* to avoid flickr, nextScene MUST be here: after tick and before draw.
     XXX: Which bug is this one. It seems that it can't be reproduced with v0.9 */
    if (m_pNextScene)
    {
        setNextScene();
    }

    kmGLPushMatrix();

    // draw the scene
    if (m_pRunningScene)
    {
        m_pRunningScene->visit();
    }

    // draw the notifications node
    if (m_pNotificationNode)
    {
        m_pNotificationNode->visit();
    }

    if (m_bDisplayStats)
    {
        showStats();
    }

    kmGLPopMatrix();

    m_uTotalFrames++;

    // swap buffers
    if (m_pobOpenGLView)
    {
        m_pobOpenGLView->swapBuffers();
    }

    if (m_bDisplayStats)
    {
        calculateMPF();
    }
}

帧渲染由mainLoop调用的drawScene()完成,drawScene方法根据Scene下的渲染树,根据node的最新属性逐个渲染 node,并调整各个Node的调度定时器数据,细节这里就不详细说明了。

九、UI线程与GLThread的交互

用户的屏幕触控动作由UI线程捕捉到,该类事件需要传递给引擎,并由GLThread根据各个画面元素的最新状态重新绘制画面。UI线程负责处理用户交互 事件,并将特定的事件通知GLThread处理。UI线程通过Cocos2dxGLSurfaceView的queueEvent方法,将事件以及处理方 法传递给GLThread执行的。

Cocos2dxGLSurfaceView的queueEvent方法继承自其父类GLSurfaceView:

    public void queueEvent(Runnable r) {
        mGLThread.queueEvent(r);
    }

而GLThread的queueEvent方法实现如下:

public void queueEvent(Runnable r) {
    if (r == null) {
        throw new IllegalArgumentException("r must not be null");
    }  
    synchronized(sGLThreadManager) {
        mEventQueue.add(r);
        sGLThreadManager.notifyAll();

    }  
}

该方法将event互斥地放入EventQueue,并通知阻塞在Queue上的线程取货。

运行着的GLThread实例在guardedRun中会从event队列中取出runnable event并run的。
  
while (true) {
    synchronized (sGLThreadManager) {
        while (true) {
            if (mShouldExit) {
                return;
            }  

            if (! mEventQueue.isEmpty()) {
                event = mEventQueue.remove(0);
                break;
            }  
         …….
        }  
     }  

     … …
     if (event != null) {
        event.run();
        event = null;
        continue;
    }  
    …
}

Activity的各种事件Pause、Resume、Stop以及View的各种屏幕触控事件都是通过queueEvent传递给GLThread执行的,比如:View的onKeyDown方法:

    //Cocos2dxGLSurfaceView.java
    @Override
    public boolean onKeyDown(final int pKeyCode, final KeyEvent pKeyEvent) {
        switch (pKeyCode) {
            case KeyEvent.KEYCODE_BACK:
            case KeyEvent.KEYCODE_MENU:
                this.queueEvent(new Runnable() {
                    @Override
                    public void run() {
                        Cocos2dxGLSurfaceView.this.mCocos2dxRenderer.handleKeyDown(pKeyCode);
                    }
                });
                return true;
            default:
                return super.onKeyDown(pKeyCode, pKeyEvent);
        }
    }

十、小结

有了以上的对Cocos2d-x引擎的理解后,再编写游戏代码就更加游刃有余了,至少出现问题时,我们知道应该在哪里查找了。就像对汽车的发动机了如指掌 后,一旦发生动力故障,我们基本知道排除的方法。但对发动机了解的再透彻,也不能代表就能设计和生产出好车,游戏也是这样,对引擎了解是一码事,设计和实 现出好游戏是另外一码事。学习引擎只是编写游戏的起点而已。

只为那一抹释然

一切没有目标的努力,都是瞎忙活儿。
                                                    - Tony Bai

刚实施回来,就又投入到新工作中,到今天才有那么一点点时间写写这件事儿。

* 缘起

我们的遗留系统性能一直不高,导致这一局面的因素有很多,比如最初设计和实现的“考虑不足”、后续维护人员的“随波逐流”甚至缺少勇气对影响性能的关 键代码进行重构等等。技术债务就这样一直积累着。直到两年前,我们终见其导致的巨大的影响了。

由于客户方成本压缩,单节点性能低意味着需要更多的硬件投入,并连带着报价升高,导致我们的产品市场竞争力下降。而竞争对手产品的性能是我们的 3-5倍,这终于引起了领导的重视,并下达了开发高性能版本的任务命令。

* 抉择

遗留系统的问题有很多,性能差仅仅是表象之一。可维护性差更让人印象深刻。遗留系统就像一件打满补丁的旧衣裳,虽然依旧能穿着遮体御寒,但却让我 们时刻战战兢兢,生怕一个动作会导致它解体,变得支离破碎。

对于我们这样一个mission-critical的系统来说,开发周期显然是不会短的。在性能达标的同时,更为重要的是保证产品的质量,确保上 线后运行稳定。因此摆在我们面前有两条路:
    1、在遗留系统上做“大修” – 大规模重构
    2、重写,把构成系统的骨架重新设计和实现,使它能够足够坚固,满足在“高速公路”上驰骋的要求。

我们最终选择了重写,也就是风险较大的那条路。在我们的理解中,重写软件就好比汽车升级平台,就像大众将传统的PQ25、PQ35等统统升级为 MQB平台那样。平台的升级,不光影响技术,还会影响方方面面,比如团队的能力、思维方式、合作模式以及团队过程改善等等。做 得好的话,会使整个团队迈上一个新台阶,这是原地修补所不能够带来的。

对于我个人来说,这也是我期望中的实验田,我将把之前研究的诸多实践落地,帮助团队提升能力。

自私地说,重写系统也是我的一个小理想,能遇到这样一个从无到有构建一个系统的机会是不多的,因此很是希望能看到一个系统一点一点的在自己的呵护 下“成长”起来。虽然我也清楚完成这样一个系统需要很长时间,而这期间我可能需要时刻紧绷着神经,直到系统正式上线后,才能感受到那一抹释然。

* 建立“骨架(skeleton)”

我们将项目分成两个阶段:建立系统“骨架”和为系统“添肉”,即添加业务逻辑。

系统的性能目标是原遗留系统的10倍,这样我们建立的骨架的性能至少要高于原遗留系统的10倍。在“添肉”之前我们要充分证明骨架的设计是合理、 有效、稳定和高性能的。

遗留系统性能低,并非因为当初的设计者能力有什么问题,更多是局限于当初的设计目标。系统初期业务量不大,接入的外部网元不多,因此系统大量使用 了链表这种简单但低效的数据结构;为了easy coding,当初的设计者选择了全局大锁;在客户端-服务器处理模型上,选择了一个连接一个进程的“高耗能”模式。最初这样的设计应对当年的业务量也是 绰绰有余的,但应付今天的业务规模就显得颇为捉襟见肘了,以至于我们不得不通过罗列机器来满足业务增长的状况。服务器增多,却导致了我们维护 和监控难度的增加。

为了应付现有业务量规模以及未来若干年的业务量增长,我们的新系统的骨架在设计时显然要扬长避短:
    – 我们重新设计了通用的服务端框架和客户端框架,使得系统各个业务模块采用相同的通信处理机制;
    – 我们没有选择线程,而是依旧采用成熟的进程(资源隔离式) + IO多路复用(linux下epoll机制)的服务器-客户端模型,与以往不同的是,我们在每个进程中处理多个链接,设定进程数量在合理水平,避免大量上下文切换带来的性能损耗;
    – 将传统的全局big lock更换成了细粒度锁;
    – 采用高效的数据结构和算法,比如用hash和array替代掉list等;
    – 用简单队列替换掉原先复杂的队列调度结构,降低代码理解难度和后续维护门槛。
    – … …

我们要求对骨架代码进行严格的单元测试,通过lcut为骨架代码建立起单元测试集,并结合持续集成对骨架代码进行持续的单元测试验证。

骨架完成后,我们对其进行了全面的压力测试,确保其性能水平达到我们设计要求,这是我们进入下一阶段的前提条件。

* 添肉(business logic)

有了稳定、可靠、高效的骨架,我们在”添肉“阶段就更加有信心了。用C写纯业务逻辑是苦逼了一些,但还好我们没有全部将以前遗留代码扔掉,我们为了保证功 能Feature不丢失,我们会尽量复用之前的业务逻辑,当然是“规范地”搬到新系统中的,尽可能地去除原有代码中的Bad smell

与骨架相比,业务逻辑相对复杂,且耦合较多,因此对这些业务逻辑做单元测试真是一件让人头疼的事情。不过这也和我们最初的估计相符,最初制定的策略就是对骨架代码做高覆盖,对业务代码则宽松些,尽量覆盖即可。

* 附加实践

就像前面所说的那样,围绕着这次重写系统,我策划了很多实践有了落脚之地,包括:
    – 试点知识管理 :通过这次重写,建立起关于该系统的知识库;
    – 增加基于ReviewBoard在线代码评审环节;
    – 引入基于Jenkins持续集成
    – 重新思考和设计构建环节,通过buildc提高构建效率;
    – 重新设计通用安装包
    – 使用LCUT对骨架进行单元测试覆盖;
    – 规范commit log以及代码提交流程
    – 应用代码风格检查工具,使得所有代码风格一致。

事实证明上述实践在这次系统重写的过程中产生了很好的效果,尤其在代码质量保证方面,系统上线后的结果也恰恰印证了这一点。

* 上线

“丑媳妇总要见公婆”。我们的新系统也到了该上线服务的时候了。为了这次上线,我们做了较为充分的实施准备,无论是人员还是时间,都有倾向性的向这个系统 投入。我们也提前做好了应对各种突发问题的预案。可实际情况出乎预料,与遗留系统的版本升级相比,这次全新系统上线显得十分顺利,系统的核心相当稳定,出 现的一些问题也都比较边缘,对这次成功上线已经不构成什么影响了。

* 那一抹释然

在实施人员庆贺上线成功时,在领导口头表扬时,我的内心却显得十分平静。对于新系统来说,这是一个好的开始。对我个人来说,我感受到了那一抹期望已久的释 然。在这个领域里这个方向上已经摸爬滾打了多年,虽然还有好多地方需要改进,好多实践需要完善,但我的内心告诉我:“够了”、“已经没什么牵挂了”、“是 时候换换方向、换换领域了”、“让其他人去做吧”。我已经在产品和团队中融入了我的思想,我相信他们都能很好的演化和发展。而我则为接受新思想、新领域做 好了准备。

的确也到了为自己设立新目标的时候了!

Recommended C Style and Coding Standards中文版全文

今天无意中打开了托管在Google Code上的“Recommended C Style and Coding Standards”翻译项目,忽感觉通过目录链接的方式查看译文缺少整体感,于是花了点时间将译文全文以single page的形式贴在博客里面,方便大家查看,也算是对该翻译内容的一个备份吧。

C语言编码风格和标准

0. 摘要

本文翻译自《Recommended C Style and Coding Standards》。

作者信息:

L.W. Cannon (Bell Labs)
R.A. Elliott (Bell Labs)
L.W. Kirchhoff (Bell Labs)
J.H. Miller (Bell Labs)
J.M. Milner (Bell Labs)
R.W. Mitze (Bell Labs)
E.P. Schan (Bell Labs)
N.O. Whittington (Bell Labs)
Henry Spencer (Zoology Computer Systems, University of Toronto)
David Keppel (EECS, UC Berkeley, CS&E, University of Washington)
Mark Brader (SoftQuad? Incorporated, Toronto)

本文是《Indian Hill C Style and Coding Standards》的更新版本,上面提到的最后三位作者对其进行了修改。本文主要介绍了一种C程序的推荐编码标准,内容着重于讲述编码风格,而不是功能 组织(Functional Organization)。

1. 简介

本文档修改于AT&T Indian Hill实验室内部成立的一个委员会的一份文档,旨在于建立一套通用的编码标准并推荐给Indian Hill社区。

本文主要讲述编码风格。良好的风格能够鼓励大家形成一致的代码布局,提高代码可移植性并且减少错误数量。

本文不关注功能组织,或是一些诸如如何使用goto的一般话题。我们尝试将之前的有关C代码风格的文档整合到一套统一的标准中,这套标准将适合于 任何使用C语言的工程,当然还是会有部分内容是针对一些特定系统的。另外不可避免地是这些标准仍然无法覆盖到所有情况。经验以及广泛的评价十分重 要,遇到特殊情况时,大家应该咨询有经验的C程序员,或者查看那些经验丰富的C程序员们的代码(最好遵循这些规则)。

本文中的标准本身并不是必需的,但个别机构或团体可能部分或全部采用该标准作为程序验收的一部分。因此,在你的机构中其他人很可能以一种相似的风 格编码。最终,这些标准的目的是提高可移植性,减少维护工作,尤其是提高代码的清晰度。

这里很多风格的选择都有些许武断。混合的编码风格比糟糕的编码风格更难于维护,所以当变更现有代码时,最好是保持与现有代码风格一致,而不是盲目 地遵循本文档中的规则。

"清晰的是专业的;不清晰的则是外行的" — Sir Ernest Gowers

2. 文件组织

一个文件包含的各个部分应该用若干个空行分隔。虽然对源文件没有最大长度限制,但超过1000行的文件处理起来非常不方便。编辑器很可能没有足够 的临时空间来编辑这个文件,编译过程也会因此变得十分缓慢。与回滚到前面所花费的时间相比,那些仅仅呈现了极少量信息的多行星号是不值得的,我们 不鼓励使用。超过79列的行无法被所有的终端都很好地处理,应该尽可能的避免使用。过长的行会导致过深的缩进,这常常是一种代码组织不善的症状。

2.1 文件命名惯例

文件名由一个基础名、一个可选的句号以及后缀组成。名字的第一个字符应该是一个字母,并且所有字符(除了句号)都应该是小写的字母和数字。基础名 应该由八个或更少的字符组成,后缀应该由三个或更少的字符组成(四个,如果你包含句号的话)。这些规则对程序文件以及程序使用和产生的默认文件都 适用(例如,"rogue.sav")。

一些编译器和工具要求文件名符合特定的后缀命名约定。下面是后缀命名要求:

    C源文件的名字必须以.c结尾
    汇编源文件的名字必须以.s结尾

我们普遍遵循以下命名约定:

    可重定位目标文件名以.o结尾
    头文件名以.h结尾
        在多语言环境中一个可供选择的更好的约定是用语言类型和.h共同作为后缀(例如,"foo.c.h" 或 "foo.ch")。

    Yacc源文件名以.y结尾
    Lex源文件名以.l结尾

C++使用编译器相关的后缀约定,包括.c,..c,.cc,.c.c以及.C。由于大多C代码也是C++代码,因此这里并没有一个明确的方案。

此外,我们一般约定使用"Makefile"(而不是"makefile")作为make(对于那些支持make的系统)工具的控制文件,并且使 用"README"作为简要描述目录内容或目录树的文件。

2.2 程序文件

下面是一个程序文件各个组成部分的推荐排列顺序:

文件的第一部分是一个序,用于说明该文件中的内容是什么。对文件中的对象(无论它们是函数,外部数据声明或定义,或是其他一些东西)用途的描述比 一个对象名字列表更加有用。这个序可选择地包含作者信息、修订控制信息以及参考资料等。

接下来是所有被包含的头文件。如果某个头文件被包含的理由不是那么显而易见,我们需要通过增加注释说明原因。大多数情况下,类似stdio.h这 样的系统头文件应该被放在用户自定义头文件的前面。

接下来是那些用于该文件的defines和typedefs。一个常规的顺序是先写常量宏、再写函数宏,最后是typedefs和枚举 (enums)定义。

接下来是全局(外部)数据声明,通常的顺序如下:外部变量,非静态(non-static)全局变量,静态全局变量。如果一组定义被用于部分特定 全局数据(如一个标志字),那么这些定义应该被放在对应数据声明后或嵌入到结构体声明中,并将这些定义缩进到其应用的声明的第一个关键字的下一个 层次(译注:实在没有搞懂后面这句的含义)。

最后是函数,函数应该以一种有意义的顺序排列。相似的函数应该放在一起。与深度优先(函数定义尽可能在他们的调用者前后)相比,我们应该首选广度 优先方法(抽象层次相似的函数放在一起)。这里需要相当多的判断。如果定义大量本质上无关的工具函数,可考虑按字母表顺序排列。

2.3 头文件

头文件是那些在编译之前由C预处理器包含在其他文件中的文件。诸如stdio.h的一些头文件被定义在系统级别,所有使用标准I/O库的程序必须 包含它们。头文件还用来包含数据声明和定义,这些数据不止一个程序需要。头文件应该按照功能组织,例如,独立子系统的声明应该放到独立的头文件 中。如果一组声明在代码从一种机器移植到另外一种机器时变动的可能性很大,那么这些声明也应该被放在独立的头文件中。

避免私有头文件的名字与标准库头文件的名字一样。下面语句:

#include "math.h"

当预期的头文件在当前目录下没有找到时,它将会包含标准库中的math头文件。如果这的确是你所期望发生的,那么请加上注释。包含头文件时不要使 用绝对路径。当从标准位置获取头文件时,请使用<name>包含头文件;或相对于当前路径定义它们。C编译器的"include- path"选项(在许多系统中为-l)是处理扩展私有库头文件的最好方法,它允许在不改变源码文件的情况下重新组织目录结构。

声明了函数或外部变量的头文件应该被那些定义了这些函数和变量的文件所包含。这样一来,编译器就可以做类型检查了,并且外部声明将总是与定义保持 一致。

在头文件中定义变量往往是个糟糕的想法,它经常是一个在文件间对代码进行低劣划分的症状。此外,在一次编译中,像typedef和经过初始化的数 据定义无法被编译器看到两次。在一些系统中,重复的没有使用extern关键字修饰的未初始化定义也会导致问题。当头文件嵌套时,会出现重复的声 明,这将导致编译失败。

头文件不应该嵌套。一个头文件的序应该描述其使用的其他被包含的头文件的实用特性。在极特殊情况下,当大量头文件需要被包含在多个不同的源文件中 时,可以被接受的做法是将公共的头文件包含在一个单独的头文件中。

一个通用的做法是将下面这段代码加入到每个头文件中以防止头文件被意外多次包含。

#ifndef EXAMPLE_H
#define EXAMPLE_H
 …    /* body of example.h file */
#endif /* EXAMPLE_H */

我们不应该对这种避免多次包含的机制产生依赖,特别是不应该因此而嵌套包含头文件。

2.4 其他文件

还有一个惯例就是编写一个名为"README"的文件,用于描述程序的整体情况以及问题。例如,我们经常在README包含程序所使用的条件编译 选项列表以及相关说明,还可以包含机器无关的文件列表等。

4. 声明

全局声明应该从第一列开始。在所有外部数据声明的前面都应该放置extern关键字。如果一个外部变量是一个在定义时大小确定的数组,那么这个数 组界限必须在extern声明时显示指出,除非数组的大小与数组本身编码在一起了(例如,一个总是以0结尾的只读字符数组)。重复声明数组大小对 于一些使用他人编写的代码的人特别有益。

指针修饰符*应该与变量名在一起,而不是与类型在一起。

char  *s, *t, *u;

替换

char*  s, t, u;

后者是错误的,因为实际上t和u并未如预期那样被声明为指针。

不相关的声明,即使是相同类型的,也应该独立占据一行。我们应该对声明对象的角色进行注释,不过当常量名本身足以说明角色时,使用#define 定义的常量列表则不需要注释。通常多行变量名、值与注释使用相同缩进,使得他们在一列直线上。尽量使用Tab字符而不是空格。结构体和联合体的声 明时,每个元素应该单独占据一行,并附带一条注释。{应该与结构体的tag名放在同一行,}应该放在声明结尾的第一列。

struct boat {
    int    wllength;    /* water line length in meters */
    int    type;        /* see below */
    long   sailarea;    /* sail area in square mm */
};

/* defines for boat.type */
#define    KETCH    (1)
#define    YAWL     (2)
#define    SLOOP    (3)
#define    SQRIG    (4)
#define    MOTOR    (5)

这些defines有时放在结构体内type声明的后面,并使用足够的tab缩进到结构体成员成员的下一级。如果这些实际值不那么重要的话,使用 enum会更好。

enum bt { KETCH=1, YAWL, SLOOP, SQRIG, MOTOR };
struct boat {
    int     wllength;    /* water line length in meters */
    enum bt type;        /* what kind of boat */
    long    sailarea;    /* sail area in square mm */
};

任何初值重要的变量都应该被显式地初始化,或者至少应该添加注释,说明依赖C的默认初始值0。空初始化"{}"应该永远不被使用。结构体初始化应 该用大括号完全括起来。用于初始化长整型(long)的常量应该使用显式长度。使用大写字母,例如2l看起来更像21,数字二十一。

int   x = 1;
char  *msg = "message";
struct boat    winner[] = {
    { 40, YAWL, 6000000L },
    { 28, MOTOR, 0L },
    { 0 },
};

如果一个文件不是独立程序,而是某个工程整体的一部分,那么我们应该最大化的利用static关键字,使得函数和变量对于单个文件来说是局部范畴 的。只有在有清晰需求且无法通过其他方式实现的特殊情况时,我们才允许变量被其他文件访问。这种情况下应该使用注释明确告知使用了其他文件中的变 量;注释应该说明其他文件的名字。如果你的调试器遮蔽了你需要在调试阶段查看的静态对象,那么可以将这些变量声明为STATIC,并根据需要决定 是否#define STATIC。

最重要的类型应该被typedef,即使他们只是整型,因为独立的名字使得程序更加易读(如果只有很少的几个integer的typedef)。 结构体在声明时应该被typedef。保持结构体标志的名字与typedef后的名字相同。

typedef struct splodge_t {
    int  sp_count;
    char *sp_name, *sp_alias;
} splodge_t;

总是声明函数的返回类型。如果函数原型可用,那就使用它。一个常见的错误就是忽略那些返回double的外部数学函数声明。那样的话,编译器就会 假定这些函数的返回值为一个整型数,并且将bit位逐一尽职尽责的注意转换为一个浮点数(无意义)。

"C语言的观点之一是程序员永远是对的" — Michael DeCorte

5. 函数声明

每个函数前面应该放置一段块注释,概要描述该函数做什么以及(如果不是很清晰)如何使用该函数。重要的设计决策讨论以及副作用说明也适合放在注释 中。避免提供那些代码本身可以清晰提供的信息。

函数的返回类型应该单独占据一行,(可选的)缩进一个级别。不用使用默认返回类型int;如果函数没有返回值,那么将返回类型声明为void。如 果返回值需要大段详细的说明,可以在函数之前的注释中描述;否则可以在同一行中对返回类型进行注释。函数名(以及形式参数列表)应该被单独放在一 行,从第一列开始。目的(返回值)参数一般放在第一个参数位置(从左面开始)。所有形式参数声明、局部声明以及函数体中的代码都应该缩进一级。函 数体的开始括号应该单独一行,放在开始处的第一列。

每个参数都应该被声明(不要使用默认类型int)。通常函数中每个变量的角色都应该被描述清楚,我们可以在函数注释中描述,或如果每个声明单独一 行,我们可以将注释放在同一行上。像循环计数器"i",字符串指针"s"以及用于标识字符的整数类型"c"这些简单变量都无需注释。如果一组函数 都拥有一个相似的参数或局部变量,那么在所有函数中使用同一个名字来标识这个变量是很有益处的(相反,避免在相关函数中使用一个名字标识用途不同 的变量)。不同函数中的相似参数还应该放在各个参数列表中的相同位置。

参数和局部变量的注释应该统一缩进以排成一列。局部变量声明应用一个空行与函数语句分隔开来。

当你使用或声明变长参数的函数时要小心。目前在C中尚没有真正可移植的方式处理变长参数。最好设计一个使用固定个数参数的接口。如果一定要使用变 长参数,请使用标准库中的宏来声明具有变长参数的函数。

如果函数使用了在文件中没有进行全局声明的外部变量(或函数),我们应该在函数体内部使用extern关键字单独对这些变量进行声明。

避免局部声明覆盖高级别的声明。尤其是,局部变量不应该在嵌套代码块中被重声明。虽然这在C中是合法的,但是当使用-h选项时,潜在的冲突可能性 足以让lint工具发出抱怨之声。

6. 空白

int i;main(){for(;i["] o, world!\n",'/'/'/'));}read(j,i,p){write(j/p+p,i—j,i/i);}
- 不光彩的事情,模糊C代码大赛,1984年。作者要求匿名。

通常情况下,请使用纵向和横向的空白。缩进和空格应该反映代码的块结构。例如,在一个函数定义与下一个函数的注释之间,至少应该有两行空白。

如果一个条件分支语句过长,那就应该将它拆分成若干单独的行。

if (foo->next==NULL && totalcount<needed && needed<=MAX_ALLOT
    && server_active(current_input)) { …

也许下面这样更好

if (foo->next == NULL
    && totalcount < needed && needed <= MAX_ALLOT
    && server_active(current_input))
{
    …

类似地,复杂的循环条件也应该被拆分为不同行。

for (curr = *listp, trail = listp;
    curr != NULL;
    trail = &(curr->next), curr = curr->next )
{
    …

其他复杂的表达式,尤其是那些使用了?:操作符的表达式,最好也能拆分成多行。

c = (a == b)
    ? d + f(a)
    : f(b) – d;

当关键字后面有放在括号内的表达式时,应该使用空格将关键字与左括号分隔(sizeof操作符是个例外)。在参数列表中,我们也应该使用空格显式 的将各个参数隔开。然而,带有参数的宏定义一定不能在名字与左括号间插入空格,否则C预编译器将无法识别后面的参数列表。

7. 例子

        /*
     * Determine if the sky is blue by checking that it isn't night.
     * CAVEAT: Only sometimes right.  May return TRUE when the answer
     * is FALSE.  Consider clouds, eclipses, short days.
     * NOTE: Uses 'hour' from 'hightime.c'.  Returns 'int' for
     * compatibility with the old version.
     */
    int  /* true or false */
    skyblue()
    {
        extern int hour;   /* current hour of the day */

        return (hour >= MORNING && hour <= EVENING);
    }

    /*
     * Find the last element in the linked list
     * pointed to by nodep and return a pointer to it.
     * Return NULL if there is no last element.
     */
    node_t *
    tail(nodep)
    node_t  *nodep;     /* pointer to head of list */
    {
       register node_t *np; /* advances to NULL */
       register node_t *lp; /* follows one behind np */

       if (nodep == NULL)
            return (NULL);
       for (np = lp = nodep; np != NULL; lp = np, np = np->next)
            ;       /* VOID */
       return (lp);
    }

8. 简单语句

每行只应该有一条语句,除非多条语句关联特别紧密。

case FOO:  oogle (zork);  boogle (zork);  break;
case BAR:  oogle (bork);  boogle (zork);  break;
case BAZ:  oogle (gork);  boogle (bork);  break;

for或while循环语句的空体应该单独放在一行并加上注释,这样可以清晰的看出空体是有意而为,并非遗漏代码。

while (*dest++ = *src++)
    ;    /* VOID */

不要对非零表达式进行默认测试,例如:

if (f() != FAIL)

比下面的代码更好

if (f())

即使FAIL的值可能为0(在C中0被认为是假)。当后续有人决定使用-1替代0作为失败返回值时,一个显式的测试将解决你的问题。即使比较的值 永远不会改变,我们也应该使用显式的比较;例如

if (!(bufsize % sizeof(int)))

应该被写成

if ((bufsize % sizeof(int)) == 0)

这样可以反映这个测试的数值(非布尔)本质。一个常见的错误点是使用strcmp测试字符串是否相同,这个测试的结果永远不应该被放弃。比较好的 方法是定义一个宏STREQ。

#define STREQ(a, b) (strcmp((a), (b)) == 0)

对谓词或满足下面约束的表达式,非零测试经常被放弃:

    0表示假,其他都为真。
    通过其命名可以看出返回真是显而易见的。

用isvalid或valid称呼一个谓词,不要用checkvalid。

一个非常常见的实践就是在一个全局头文件中声明一个布尔类型"bool"。这个特殊的名字可以极大地提高代码可读性。

typedef int    bool;
#define FALSE    0
#define TRUE    1

typedef enum { NO=0, YES } bool;

即便有了这些声明,也不要检查一个布尔值与1(TRUE,YES等)的相当性;可用测试与0(FALSE,NO等)的不等性替代。绝大多数函数都 可以保证为假的时候返回0,但为真的时候只返回非零。

if (func() == TRUE) { …

必须被写成

if (func() != FALSE) { …

如果可能的话,最好为函数/变量重命名或者重写这个表达式,这样就可以显而易见的知道其含义,而无需再与true或false比较了(例如,重命 名为isvalid())。

嵌入赋值语句也有用武之地。在一些结构中,在没有降低代码可读性的前提下,没有比这更好的方式来实现这个结果了。

while ((c = getchar()) != EOF) {
    process the character
}

++和–操作符可算作是赋值语句。这样,为了某些意图,实现带有副作用的功能。使用嵌入赋值语句也可能提高运行时的性能。不过,大家应该在提高 的性能与下降的可维护性之间做好权衡。当在一些人为的地方使用嵌入赋值语句时,这种情况会发生,例如:

a = b + c;
d = a + r;

不应该被下面代码替代:

d = (a = b + c) + r;

即使后者可能节省一个计算周期。在长期运行时,由于优化器渐获成熟,两者的运行时间差距将下降,而两者在维护性方面的差异将提高,因为人类的记忆 会随着时间的流逝而衰退。

在任何结构良好的代码中,goto语句都应该保守地使用。使用goto带来好处最大的地方是从switch、for和while多层嵌套中跳出, 但这样做的需求也暗示了代码的内层结构应该被抽取出来放到一个单独的返回值为成功或失败的函数中。

    for (…) {
        while (…) {
            …
            if (disaster)
                goto error;

        }
    }
    …
error:
    clean up the mess

当需要goto时候,其对应的标签应该被放在单独一行,并且后续的代码缩进一级。使用goto语句时应该增加注释(可能放在代码块的头)以说明它 的功用和目的。continue应该保守地使用,并且尽可能靠近循环的顶部。Break的麻烦比较少。

非原型函数的参数有时需要被显式做类型提升。例如,如果函数期望一个32bit的长整型,但却被传入一个16bit的整型数,可能会导致函数栈不 对齐。指针,整型和浮点值都会发生此问题。

9. 复合语句

复合语句是一个由括号括起来的语句列表。有许多种常见的括号格式化方式。如果你有一个本地标准,那请你与本地标准保持一致,或选择一个标准,并持 续地使用它。在编辑别人的代码时,始终使用那些代码中使用的样式。

control {
       statement;
       statement;
}

上面的风格被称为"K&R风格",如果你还没有找到一个自己喜欢的风格,那么可以优先考虑这个风格。在K&R风格中,if- else语句中的else部分以及do-while语句中的while部分应该与结尾大括号在同一行中。而其他大部分风格中,大括号都是单独占据 一行的。

当一个代码块拥有多个标签时,每个标签应该单独放在一行上。必须为C语言的switch语句的fall-through特性(即在代码段与下一个 case语句之前间没有break)增加注释以利于后期更好的维护。最好是lint风格的注释/指示。

switch (expr) {
case ABC:
case DEF:
     statement;
    break;
case UVW:
     statement;
     /*FALLTHROUGH*/
case XYZ:
    statement;
    break;
}

这里,最后那个break是不必要的,但却是必须的,因为如果后续另外一个case添加到最后一个case的后面时,它将阻止fall- through错误的发生。如果使用default case,那么应该该default case放在最后,且不需要break,如果它是最后一个case。

一旦一个if-else语句在if或else段中包含一个复合语句,if和else两个段都应该用括号括上(称为全括号(fully bracketed)语法)。

if (expr) {
    statement;
} else {
    statement;
    statement;
}

在如下面那样的没有第二个else的if-if-else语句序列里,括号也是不必可少的。如果ex1后面的括号被省略,编译器解析将出错:

if (ex1) {
    if (ex2) {
         funca();
    }
} else {
    funcb();
}

一个带else if的if-else语句在书写上应该让else条件左对齐。

if (STREQ (reply, "yes")) {
    statements for yes
    …
} else if (STREQ (reply, "no")) {
    …
} else if (STREQ (reply, "maybe")) {
    …
} else {
    statements for default
    …
}

这种格式看起来像一个通用的switch语句,并且缩进反映了在这些候选语句间的精确切换,而不是嵌套的语句。

Do-while循环总是使用括号将循环体括上。

下面的代码非常危险:

#ifdef CIRCUIT
#    define CLOSE_CIRCUIT(circno) { close_circ(circno); }
#else
#    define CLOSE_CIRCUIT(circno)
#endif


if (expr)
    statement;
else
    CLOSE_CIRCUIT(x)
++i;

注意,在CIRCUIT没有定义的系统上,语句++i仅仅在expr是假的时候获得执行。这个例子指出宏用大写命名的价值,以及让代码完全括号化 的价值。

有些时候,通过break,continue,goto或return,if可以无条件地进行控制转移。else应该是隐式的,并且代码不应该缩 进。

if (level > limit)
    return (OVERFLOW)
normal();
return (level);

平坦的缩进告诉读者布尔测试在密封块的其他部分是保持不变的。

10. 操作符

一元操作符不应该与其唯一的操作数分开。通常,所有其他二元操作符都应该使用空白与其操作树分隔开,但'.'和'->'例外。当遇到复杂表 达式的时候我们需要做出一些判断。如果内层操作符没有使用空白分隔而外层使用了,那么表达式也许会更清晰些。

如果你认为一个表达式很难于阅读,可以考虑将这个表达式拆分为多行。在接近中断点的最低优先级操作符处拆分是最好的选择。由于C具有一些想不到的 优先级规则,混合使用操作符的表达式应该使用括号括上。但是过多的括号也会使得代码可读性变差,因为人类不擅长做括号匹配。

二元逗号操作符也会被使用到,但通常我们应该避免使用它。逗号操作符的最大用途是提供多元初始化或操作,比如在for循环语句中。复杂表达式,例 如那些使用了嵌套三元?:操作符的表达式,可能引起困惑,并且应该尽可能的避免使用。三元操作符和逗号操作符在一些使用宏的地方很有用,诸如 getchar。在三元操作符?:前的逻辑表达式的操作数应该被括起来,并且两个子表达式的返回值应该是相同类型。

11. 命名约定

毫无疑问,每个独立的工程都有一套自己的命名约定,不过仍然有一些通用的规则值得参考。

    * 为系统用途保留以下划线开头或下划线结尾的名字,并且这些名字不应该被用在任何用户自定义的名字中。大多数系统使用这些名字用于用户不应 该也不需知道的名字中。如果你一定要使用你自己私有的标识符,可以用标识它们归属的包的字母作为开头。

    * #define定义的常量名字应该全部大写。

    * Enum常量应该大写或全部大写。

    * 函数名、typedef名,变量名以及结构体、联合体与枚举标志的名字应该用小写字母。

    * 很多"宏函数"都是全部大写的。一些宏(诸如getchar和putchar)使用小写字母命名,这事因为他们可能被当成函数使用。只有在宏的行为类似一 个函数调用时才允许小写命名的宏,也就是说它们只对其参数进行一次求值,并且不会给具名形式参数赋值。有些时候我们无法编写出一个具有函数行为的 宏,即使其参数也只是求值一次。

    * 避免在同一情形下使用不同命名方式,比如foo和Foo。同样避免foobar和foo_bar这种方式。需要考虑这样所带来的困惑。

    * 同样,避免使用看起来相似的名字。在很多终端以及打印设备上,'I'、'1'和'l'非常相似。给变量命名为l特别糟糕,因为它看起来十分像常量'1'。

通常,全局名字(包括enum)应该具有一个统一的前缀,通过该前缀名我们可以识别出这个名字归属于哪个模块。全局变量可以选择汇集在一个全局结 构中。typedef的名字通常在结尾加一个't'。

避免名字与各种标准库中的名字冲突。一些系统可能包含一些你所不需要的库。另外你的程序将来某天很可能也要扩展。

12. 常量

数值型常量不应该被硬编码到源文件中。应该使用C预处理器的#define特性为常量赋予一个有意义的名字。符号化的常量可以让代码具有更好的可 读性。在一处地方统一定义这些值也便于进行大型程序的管理,这样常量值可以在一个地方进行统一修改,只需修改define的值即可。枚举数据类型 更适合声明一组具有离散值的变量,并且编译器还可以对其进行额外的类型检查。至少,任何硬编码的值常量必须具有一段注释,以说明该值的来历。

常量的定义应该与其使用是一致的;例如使用540.0作为一个浮点数,而不是使用540外加一个隐式的float类型转换。有些时候常量0和1被 直接使用而没有用define进行定义。例如,一个for循环语句中用于标识数组下标的常量,

for (i = 0; i < ARYBOUND; i++)

上面代码是合理的,但下面代码

door_t *front_door = opens(door[i], 7);
if (front_door == 0)
    error("can't open %s\\\\n", door[i]);

是不合理的。在最后的那个例子中,front_door是一个指针。当一个值是指针的时候,它应该与NULL比较而不是与0比较。NULL被定义 在标准I/O库头文件stdio.h中,在一些新系统中它在stdlib.h中定义。即使像1或0这样的简单值,我们最好也用define定义成 TRUE和FALSE定义后再使用(有些时候,使用YES和NO可读性更好)。

简单字符常量应该被定义成字面值,不应该使用数字。不鼓励使用非可见文本字符,因为它们是不可移植的。如果非可见文本字符十分必要,尤其是当它们 在字符串中使用时,它们应该定义成三个八进制数字的转义字符(例如: '\007‘)而非一个字符。即使这样,这种用法也应该考虑其机器相关性,并按这里的方法处理。

13. 宏

复杂表达式可能会被用作宏参数,这可能会因操作符优先级顺序而引发问题,除非宏定义中所有参数出现的位置都用括号括上了。对这种因参数内副作用而 引发的问题,我们似乎也无能为例,除了在编写表达式时杜绝副作用(无论如何,这都是一个很好的主意)。如果可能的话,尽量在宏定义中对宏参数只进 行一次求值。有很多时候我们无法写出一个可像函数一样使用的宏。

一些宏也当成函数使用(例如,getc和fgetc)。这些宏会被用于实现其他函数,这样一旦宏自身发生变化,使用该宏的函数也会受到影响。在交 换宏和函数时务必要小心,因为函数参数是按值传递的,而宏参数则是通过名称替换。只有在宏定义时特别谨慎小心,才有可能减少使用宏时的担心。

宏定义中应该避免使用全局变量,因为全局变量的名字很可能被局部声明遮盖。对于那些对具名参数进行修改(不是这些参数所指向的存储区域)或被用作 赋值语句左值的宏,我们应该添加相应的注释以给予提醒。那些不带参数但引用变量,或过长或作为函数别名的宏应该使用空参数列表,例如:

#define    OFF_A()    (a_global+OFFSET)
#define    BORK()    (zork())
#define    SP3()    if (b) { int x; av = f (&x); bv += x; }

宏节省了函数调用和返回的额外开销,但当一个宏过长时,函数调用和返回的额外开销就变得微不足道了,这种情况下我们应该使用函数。

在一些情况下,让编译器确保宏在使用时应该以分号结尾是很有必要的。

if (x==3)
    SP3();
else
    BORK();

如果省略SP3调用后面的分号,后面的else将会匹配到SP3宏中的那个if。有了分号,else分支就不会与任何if匹配。SP3宏可以这样 安全地实现:

#define SP3() \\\\
     do { if (b) { int x; av = f (&x); bv += x; }} while (0)

手工给宏定以加上do-while包围看起来很别扭,而且很多编译器和工具会抱怨在while条件是一个常量值。一个用来声明语句的宏可以使得编 码更加容易:

#ifdef lint
    static int ZERO;
#else
#    define ZERO 0
#endif
#define STMT( stuff ) do { stuff } while (ZERO)

我们可以用下面代码来声明SP3宏:

#define SP3() \\\\
    STMT( if (b) { int x; av = f (&x); bv += x; } )

使用STMT宏可以有效阻止一些可以潜在改变程序行为的打印排版错误。

除了类型转换、sizeof以及上面那些技巧和手法,只有当整个宏用括号括上时才应该包含关键字。

14. 条件编译

条件编译在处理机器依赖、调试以及编译阶段设定特定选项时十分有用。不过要小心条件编译。各种控制很容易以一种无法预料的方式结合在一起。如果使 用#ifdef判断机器依赖,请确保当没有机器类型适配时,返回一个错误,而不是使用默认机器类型(使用#error并缩进一级,这样它可以一些老旧的编 译器下工作)。如果你#ifdef优化选项,默认情况下应该是一个未经优化的代码,而不是一个不兼容的程序。确保测试的是未经优化的代码。

注意在#ifdef区域内的文本可能会被编译器扫描(处理),即使#ifdef求值的结果为假。但即使文件的#ifdef部分永远不能被编译到(例如,#ifdef COMMENT),这部分也不该随意的放置文本。

尽可能地将#ifdefs放在头文件中,而不是源文件中。使用#ifdef定义可以在源码中统一使用的宏。例如,一个用于检查内存分配的头文件可能这样实现:(省略了REALLOC和FREE):

#ifdef DEBUG
    extern void *mm_malloc();
#    define MALLOC(size) (mm_malloc(size))
#else
    extern void *malloc();
#    define MALLOC(size) (malloc(size))
#endif

条件编译通常应该基于一个接一个的特性的。多数情况下,都应该避免使用机器或操作系统依赖。

#ifdef BSD4
    long t = time ((long *)NULL);
#endif

上面代码之所以糟糕有两个原因:很可能在某个4BSD系统上有更好的选择,并且也可能存在在某个非4BSD系统中上述代码是最佳代码。我们可以通过定义诸 如TIME_LONG和TIME_STRUCTD等宏作为替代,并且在诸如config.h的配置文件中定义一个合适的宏。

16. 可移植性

    "C语言结合了汇编的强大功能和可移植性" — 无名氏,暗指比尔.萨克。

可移植代码的好处是有目共睹的。这一节将阐述一些编写可移植代码的指导原则。这里"可移植的"是指一个源码文件能够在不同机器上被编译和执行,其 前提仅仅是在不同平台上可能包含不同的头文件,使用不同的编译器开关选项罢了。头文件包含的#define和typedef可能因机器而异。一般 来说,一个新"机器"是指一种不同的硬件,一种不同的操作系统,一个不同的编译器,或者是这些的任意组合。参考1包含了很多关于风格和可移植 性方面的有用信息。下面是一个隐患列表,当你设计可移植代码时应该考虑避免这些隐患:

    * 编写可移植的代码。只有当被证明是必要的情况下才考虑优化的细节。优化后的代码往往是模糊不清、难以理解的。在一台机器上经过优化后的代码,在其他机器上 可能变得更加糟糕。将采用的性能优化手段记录下来并尽可能多地本地化。文档应该解释这些手段的工作原理以及引入它们的原因(例如:"循环执行了无 数次")

    * 要意识到很多东西天生就是不可移植的。比如处理类似程序状态字这样的特定硬件寄存器的代码,以及被设计用于支持某特定硬件部件的代码,诸如汇编器以及 I/O驱动。即使在这种情况下,许多例程和数据仍然可以被设计成机器无关的。

    * 组织源文件时将机器无关与机器相关的代码分别放在不同文件中。之后如果这个程序需要被移植到一个新机器上时,我们就可以很容易判断出来哪些需要被改变。为 一些文件的头文件中机器依赖相关的代码添加注释。

    * 任何"实现相关"的行为都应该作为机器(编译器)依赖对待。假设编译器或硬件以一种十分古怪的方式实现它。

    * 注意机器字长。对象的大小可能不直观,指针大小也不总是与整型大小相同,也不总是彼此大小相同,或者可相互自由转换。下面的表中列举了C语言基本类型在不 同机器和编译器下的大小(以bit为单位)。

type    pdp11  VAX/11 68000  Cray-2 Unisys Harris 80386
        series       family          1100   H800
char     8      8      8       8      9     8      8
short    16    16     8/16   64(32)   18    24    8/16
int      16    32     16/32  64(32)   36    24    16/32
long     32    32      32    64       36    48    32
char*    16    32      32    64       72    24    16/32/48
int*     16    32      32    64(24)   72    24    16/32/48
int(*)() 16    32      32    64       576   24    16/32/48

有些机器针对某一类型可能有不止一个大小。其类型大小取决于编译器和不同的编译期标志。下面表展示了大多数系统的"安全"类型大小。无符号与带符 号数具有相同的大小(单位:bit)。

Type    Minimum  No Smaller
          # Bits   Than
char       8  
short      16    char
int        16    short
long       32    int
float      24  
double     38    float
any *      14  
char *     15    any *
void *     15    any *

    * void类型可以保证有足够位精度来表示一个指向任意数据对象的指针。void()()类型可以保证表示一个指向任意函数的指针。当你需要通用指针时 可以使用这些类型(在一些旧的编译器里,分别用char和char()()表示)。确保在使用这些指针类型之前将其转换回正确的类型。

    * 即使说一个int和一个char类型大小相同,它们仍可能具有不同的格式。例如,下面例子在一些sizeof(int)等于 sizeof(char)的机器上可能失败。其原因在与free函数期望一个char,但却传入了一个int。

    int *p = (int *) malloc (sizeof(int));
   free (p);

    * 注意,一个对象的大小不能保证这个对象的精度。Cray-2可能使用64位来存储一个整型,但一个长整型转换为一个整型并且再转换回长整型后可能会被截断 为32位。

    * 整型常量0可以强制转型为任何指针类型。转换后的指针称为对应那个类型的空指针,并且与那个类型的其他指针不同。空指针比较总是与常量0相当。空指针不应 该与一个值为0的变量比较。空指针不总是使用全0的位模式表示。两个不同类型的空指针有些时候可能不同。某个类型的空指针被强制转换为另外一个类 型的指针,其结果是该指针转换为第二个类型的空指针。

    * 对于ANSI编译器,当两个类型相同的指针访问同一块存储区时,则它们比较是相等的。当一个非0整型常量被转换为指针类型时,它们可能与其他指针相等。对 于非ANSI编译器,访问同一块存储区的两个指针比较可能并不相同。例如,下面两个指针比较可能相等或不相等,并且他们可能或可能没有访问同一块 存储区域。

    ((int *) 2 )
    ((int *) 3 )

如果你需要'magic'指针而不是NULL,要么分配一些内存,要么将指针视为机器相关的。

extern int x_int_dummy;    /* in x.c */
#define X_FAIL    (NULL)
#define X_BUSY    (&x_int_dummy)
#define X_FAIL    (NULL)
#define X_BUSY    MD_PTR1  /* MD_PTR1 from "machdep.h" */

    * 浮点数字既包含精度也包含范围。这些都是数据对象大小无关的。但是,一个32位浮点数在不同机器上溢出时的值有所不同。同时,4.9乘以5.1在不同的机 器上可能产生两个不同的数字。在圆整(rounding)和截断方面的差异将给出特别不同的答案。

    * 在一些机器上,一个双精度浮点数在精度或范围方面可能比一个单精度浮点数还要低。

    * 在一些机器上,double值的前半部分可能是一个具有相同值的float类型。千万不要依赖于此。

    * 提防带符号字符。例如,在某些VAX系统上,用在表达式中的字符是符号扩展的,但在其他一些机器上并非如此。对有符号和无符号有依赖的代码是不可移植的。 例如,如果假设c是正值,arrayc在c为有符号且为负值时将无法正常工作。如果你一定要假设signed或unsigned字符的话,请 用SIGNED或UNSIGNED为其加上注释。无符号字符的行为可由unsigned char保证。

    * 避免对ASCII做假设。如果你必须假设,那么请将其记录下来并本地化。请记住字符很可能用不止8位表示。

    * 大多数机器采用2的补码表示数,但我们在代码中不应该利用这一特点。使用等价移位操作替代算术运算的优化尤其值得怀疑。如果必须这么做,那么机器相关的代 码应该用#ifdef定义,或者操作应该在#ifdef宏判定下执行。你应该衡量一下使用这种难以理解的代码所节省的时间与做代码移植时找bug 所花费的时间相比孰多孰少。

    * 一般情况下,如果字长或值范围非常重要,应该使用typedef定义具有特定大小的类型。大型程序应该具有一个统一的头文件用于提供通用的、大小 (size)敏感的类型的typedef定义,这样更加便于修改以及在紧急修复时查找大小敏感的代码。无符号类型比有符号整型更加编译器无关。如 果既可以用16bit也可以用32bit标识一个简单for循环的计数器,我们应该使用int。因为对于当前机器来说,通过整型可以获取更高效 (自然)的存储单元。

    * 数据对齐也很重要。例如,在不同的机器上,一个四字节的整型数的可能以任意地址作为起始地址,也可能只允许以偶数地址作为起始地址,或者只能以4的整数倍 的地址作为起始地址。因此,一个特定的结构体的各个元素在不同的机器上的偏移量有不同,即使给定的这些元素在所有机器上的大小相同。事实上,一个 包含一个32位指针和一个8位字符的结构提在三个不同的机器上可能有三个不同的大小。作为一个推论,对象指针可能无法自由互换;通过一个指向起始 地址为奇数地址长度为4个字节的指针保存一个整型数有时可以正常工作,但有时则会导致产生core,有些时候静悄悄地失败了(在这个过程中会破坏 其他数据)。在那些不按字节寻址的机器上,字符指针更是"事故高发地区"。对齐考虑以及加载器的特殊性使得很容易轻率地认为两个连续声明的变量在 内存中也是连在一起的,或者某个类型的变量已经被适当对齐并可以用作其他类型变量使用了。

    * 在一些机器上,诸如VAX(小端),一个字的字节随着地址的增加,其重要性提高;而另外一些机器上,诸如68000(大端),随着地址的增加,其重要性降 低。字或更大数据对象(诸如一个双精度字)的字节顺序可能并不相同。因此,任何依赖对象内从左到右方向位模式的代码都值得特别细致的审查。只有当 结构体中两个不同的位字段不被连接以及不被当作一个单元时,这些位字段才具备可移植性。事实上,连接任意两个变量都是不可移植的行为。

    * 结构体中有一些未使用的空洞。猜想联合体用于类型欺骗。尤其是,一个值不应该在存储时使用一个类型,而在读取时使用另外一种类型。对联合体来说,一个显式 的标签(tag)字段可能会很有用。

    * 不同的编译器在返回结构体时使用不同的约定。这就会导致代码在接受从不同编译器编译的库代码中返回的结构体值时会出现错误。结构体指针不是问题。

    * 不要假设参数传递机制。特别是指针大小以及参数求值顺序,大小等。例如,下面的代码就不具备可移植性。

        c = foo (getchar(), getchar());

    char
    foo (c1, c2, c3)
    char c1, c2, c3;
    {
        char bar = *(&c1 + 1);
        return (bar);            /* often won't return c2 */
    }

    * 上面的例子有诸多问题。栈可能向上增长,也可能向下增长(事实上,甚至都不需要一个栈)。参数在传入时可能被扩大,例如一个char可能以int型被传 入。参数可能以从左到右,从右到左,或以任意顺序压入栈,或直接放在寄存器中(根本无需压栈)。参数求值的顺序也可能与压栈的次序有所不同。一个 编译器可能使用多种(不兼容的)调用约定。

    * 在某些机器上,空字符指针((char *)0)常被当作指向空字符串的指针对待。不要依赖于此。

   *  不要修改字符串常量。下面就是一个臭名昭著的例子

    s = "/dev/tty??";
  strcpy (&s[8], ttychars);

    * 地址空间可能有空洞。简单计算一个数组中未分配空间的元素(在数组实际存储区域之前或之后)的地址可能会导致程序崩溃。如果这个地址被用于比较,有时程序 可以运行,但会破坏数据,报错,或陷入死循环。在ANSI C中,指向一个对象数组的指针指向数组结尾后的第一个元素是合法的,这在一些老编译器上通常是安全的。不过这个"在外边"不可以被解引用。

    * 只有==和!=比较可用于某给定类型的所有指针。当两个指针指向同一个数组内的元素(或数组后第一个元素)时,使用<<、<=、& amp; gt;或>=对两个指针进行比较是可移植的。同样,仅仅对指向同一个数组内的元素(或数组后第一个元素)的两个指针使用算术操作符才是可移 植的。

    * 字长(word size)也影响移位和掩码。下面代码在一些68000机器上只会将一个整型数的最右三个位清0,而在其他机器上它还会将高地址的两个字节清零。x &= 0177770 使用 x &= ~07可以在所有机器上正常工作。位字段(bitfield)没有这些问题。

    * 表达式内的副作用可能导致代码语义是编译器相关的,因为在大多数情况下C语言的求值顺序是没有显式定义的。下面是一个臭名昭著的例子:

    a[i] = b[i++];

    在上面的例子中,我们只知道b的下标值没有被增加。a的下标i值可能是自增后的值也可能是自增前的值。

    struct bar_t { struct bar_t *next; } bar;
    bar->next = bar = tmp;

在第二个例子中,bar->next的地址很可能在bar被赋值之前被计算使用。

bar = bar->next = tmp;

第三个例子中,bar可能在bar->next之前被赋值。虽然这可能有悖于"赋值从右到左处理"的规则,但这确是一个合法的解析。考虑下 面的例子:

long i;
short a[N];
i = old
i = a[i] = new;

赋给i的值必须是一个按照从右到左的处理顺序进行赋值处理后的值。但是i可能在ai被赋值前而被赋值为"(long) (short)new"。不同编译器作法不同。

    * 质疑代码中出现的数值(“魔数”)。

    * 避免使用预处理器技巧。一些诸如使用/ /粘和字符串以及依赖参数字符串展开的宏会破坏代码可靠性。

    #define FOO(string)    (printf("string = %s",(string)))
    …
  FOO(filename);

只是在有些时候会扩展为

 (printf("filename = %s",(filename)))

小心。诡异的预处理器在一些机器上可能导致宏异常中断。下面是一个宏的两种不同实现版本:

  #define LOOKUP(chr)    (a['c'+(chr)])    /* Works as intended. */
  #define LOOKUP(c)    (a['c'+(c)])        /* Sometimes breaks. */

第二个版本的LOOKUP可能以两种不同的方式扩展,并且会导致代码异常中断。

    * 熟悉现有的库函数和定义(但不用太熟悉。与其外部接口相反,库基础设施的内部细节常会改变并且没有警告,这些细节常常也是不可移植的)。你不应该再自己重 新编写字符串比较例程、终端控制例程或为系统结构编写你自己的定义。自己动手实现既浪费你的时间,又使得你的代码可读性变差,因为另外一个读者需 要知道你是否在新的实现中做了什么特殊的事情,并尝试证实它们的存在。同时这样做会使得你无法充分利用一些辅助的微代码或其他有助于提高系统例程 性能的方法。更进一步,它将是一个bug的高产源头。如果可能的话,要知道公共库之间的差异(如ANSI、POSIX等等)。

    * 如果lint可用,请使用lint。这个工具对于查找代码中机器相关的构造、其他不一致性以及顺利通过编译器检查的程序bug时具有很高价值。如果你的编 译器具备打开警告的开关,请打开它。

    * 质疑在代码块内部的与代码块外部switch或goto有关联的标签(Label)。

    无论类型在哪里,参数都应该被转换为适当的类型。当NULL用在没有原型的函数调用时,请对NULL进行转换。不要让函数调用成为类型欺骗发生的地方。C 语言的类型提升规则很是让人费解,所以尽量小心。例如,如果一个函数接受一个32位长的长整型做为参数,但实际传入的却是一个16位长的整型数, 函数栈可能会无法对齐,这个值也可能会被错误提升。

    * 在混用有符号和无符号值的算术计算时请使用显式类型转换

    * 应该谨慎使用跨程序的goto、longjmp。很多实现"忘记"恢复寄存器中的值了。尽可能将关键的值声明为volatile,或将它们注释为 VOLATILE。

    * 一些链接器将名字转换为小写,并且一些链接器只识别前六个字母作为唯一标识。在这些系统上程序可能会悄悄地中断运行。

    * 当心编译器扩展。如果使用了编译器扩展,请将他们视为机器依赖并用文档记录下来。

    * 通常程序无法在数据段执行代码或者无法将数据写入代码段。即使程序可以这么做,也无法保证这么做是可靠的。

17. 标准C

现代C编译器支持一些或全部的ANSI提议的标准C。无论何时可能的话,尽量用标准C编写和运行程序,并且使用诸如函数原型,常量存储以及 volatile(易失性)存储等特性。标准C通过给优化器提供有有效的信息以提升程序的性能。标准C通过保证所有编译器接受同样的输入语言以及提供相关 机制隐藏机器相关内容或对于那些机器相关代码提供警告的方式提升代码的可移植性。

17.1 兼容性

编写很容易移植到老编译器上的代码。例如,有条件地在global.h中定义一些新(标准中的)关键字,比如const和volatile。标准编译器预 定义了预处理器符号STDC(见脚注8)。void类型很难简单地处理正确,因为很多老编译器只理解void,但不认识void。最简单的方法就是定义一 个新类型VOIDP(与机器和编译器相关),通常在老编译器下该类型被定义为char*。

#if __STDC__
    typedef void *voidp;
#   define COMPILER_SELECTED
#endif
#ifdef A_TARGET
#    define const
#    define volatile
#    define void int
    typedef char *voidp;
#    define COMPILER_SELECTED
#endif
#ifdef …
    …
#endif
#ifdef COMPILER_SELECTED
#    undef COMPILER_SELECTED
#else
    { NO TARGET SELECTED! }
#endif

注意在ANSI C中,#必须是同一行中预处理器指示符的第一个非空白字符。在一些老编译器中,它必须是同一行中的第一个字符。

当一个静态函数具有前置声明时,前置声明必须包含存储修饰符。在一些老编译器中,这个修饰符必须是"extern"。对于ANSI编译器,这个存储修饰符 必须为static,但全局函数依然必须声明为extern。因此,静态函数的前置声明应该使用一个#define,例如FWD_STATIC,并通 过#ifdef适当定义。

一个"#ifdef NAME"应该要么以"#endif"结尾,要么以"#endif / NAME /结尾,不应该用"#endif NAME"结尾。对于短小的#ifdef不应该使用注释,因为通过代码我们可以明确其含义。

ANSI的三字符组可能导致内容包含??的字符串的程序神秘的中断。

17.2 格式化

ANSI C的代码风格与常规C一样,但有两点意外:存储修饰符(storage qualifiers)和参数列表。

由于const和volatile的绑定规则很奇怪,因此每个const或volatile对象都应该单独声明。

int const *s;        /* YES */
int const *s, *t;    /* NO */

具备原型的函数将参数声明和定义归并在一个参数列表中了。应该在函数的注释中提供各个参数的注释。

/*
 * `bp': boat trying to get in.
 * `stall': a list of stalls, never NULL.
 * returns stall number, 0 => no room.
 */
int
enter_pier (boat_t const *bp, stall_t *stall)
{
    …

17.3 原型

应该使用函数原型使得代码更加健壮并且运行时性能更好。不幸地是原型的声明

extern void bork (char c);

与定义不兼容。

void
bork (c)
char c;
 …

原型中c应该以机器上最自然的类型传入,很可能是一个字节。而非原型化(向后兼容)的定义暗示c总是以一个整型传入。如果一个函数具有可类型提升的参数, 那么调用者和被调用者必须以相等地方式编译。要么都必须使用函数原型,要么都不使用原型。如果在程序设计时参数就是可以提升类型的,那么问题就可以被避 免,例如bork可以定义成接受一个整型参数。

如果定义也是原型化的,上面的声明将工作正常。

void
bork (char c)
{
    …

不幸地是,原型化的语法将导致非ANSI编译器拒绝这个程序。

但我们可以很容易地通过编写外部声明来同时适应原型与老编译器。

#if __STDC__
#    define PROTO(x) x
#else
#    define PROTO(x) ()
#endif

extern char **ncopies PROTO((char *s, short times));

注意PROTO必须使用双层括号。

最后,最好只使用一种风格编写代码(例如,使用原型)。当需要非原型化的版本时,可使用一个自动转换工具生成。

17.4 Pragmas

Pragmas用于以一种可控的方式引入机器相关的代码。很显然,pragma应该被视为机器相关的。不幸地是,ANSI pragmas的语法使得我们无法将其隔离到机器相关的头文件中了。

Pragmas分为两类。优化相关的可以被安全地忽略。而那些影响系统行为(需要pragmas)的Pragmas则不能忽略。需要的pragmas应该结合#ifdef使用,这样如果一个pragma都没有选到,编译过程将退出。

两个编译器可能通过两个不同的方式使用同一个给定的pragma。例如,一个编译器可能使用haggis发出一个优化信号。而另一个可能使用它暗示一个特 定语句,一旦执行到此,程序应该退出。不过,一旦使用了pragma,它们必须总是被机器相关的#ifdef包围。对于非ANSI编译器,Pragmas 必须总是被#ifdef。确保对#pragma的#进行缩进,否则一些较老的预处理器处理它时会挂起。

#if defined(__STDC__) && defined(USE_HAGGIS_PRAGMA)
    #pragma (HAGGIS)
#endif

    "ANSI标准中描述的'#pragma'命令具有任意实现定义的影响。在GNU C预处理中,'#pragma'首先尝试运行游戏'rogue';如果失败,它将尝试运行游戏'hack';如果失败,它将尝试运行GNU Emacs显示汉诺塔;如果失败,它将报告一个致命错误。无论如何,预处理将不再继续。"

    — GNU CC 1.34 C预处理手册。

18. 特殊考虑

这节包含一些杂项:‘做'与'不做'。

    * 不要通过宏替换来改变语法。这将导致程序对于所有人都是难以理解的,除了那个肇事者。

    * 不要在需要离散值的地方使用浮点变量。使用一个浮点数作为循环计数器无疑是搬起石头砸自己的脚。总是用<=或>=测试浮点数,对它们永远不要 用精确比较(==或!=)。

    * 编译器也有bug。常见且高发的问题包括结构体赋值和位字段。你无法泛泛的预测一个编译器都有哪些bug。但你可以在程序中避免使用那些已知的在所有编译 器上都存在问题的结构。你无法让你写的任何代码都是有用的,你可能仍然会遇到bug,并且在这期间编译器很可能会被修复。因此,只有当你被强制使 用某个特定的充斥bug的编译器时,你才应该"围绕"着编译器bug写代码。

    * 不要依赖自动代码美化工具。良好代码风格的主要受益者就是代码的编写者,并且尤其在手写算法或伪代码的早期设计阶段。自动代码美化工具只应该用在那些已经 完成、语法正确并且此后不能满足当空白和缩进被更为关注的要求时。伴随着对细致程序员的细节的关注,对于那些将函数或文件布局解释清楚的工作,程 序员们会做得更好(换句话说,一些视觉布局是由意图而不是语法决定的,美化工具无法了解到程序员的思想)。粗心的程序员应该学习成为一个细致的程 序员,而不是依赖美化工具让代码可读性更好。

    * 意外地遗漏逻辑比较表达式中的第二个=是一个常犯的问题。使用显式测试。避免对赋值使用隐式测试。

abool = bbool;
if (abool) { …

当嵌入的赋值表达式使用时,确保测试是显式的,这样后续它就无法被"修复"了。

while ((abool = bbool) != FALSE) { …
while (abool = bbool) { …    /* VALUSED */
while (abool = bbool, abool) { …

    显式地注释那些在正常控制流之外被修改的变量,或其他可能在维护过程中中断的代码。

    现代编译器会自动将变量放到寄存器中。对于你认为最关键的变量慎用寄存器。在极端情况下,用寄存器标记2-4个最为关键的值,并且将剩余的标记为 REGISTER。后者在那些具有较多寄存器的机器上可以#define为寄存器。

19. Lint

Lint是一个C程序检查工具,用于检查C语言源码文件,探测和报告诸如类型不兼容、函数定义与调用不一致以及潜在的bug等情况。强烈建议在所 有程序上使用lint工具,并且期望大多数工程将lint作为官方验收程序的一部分。

应该注意的是使用lint的最好方法不是将lint作为官方验收之前的一道必须跨过的栅栏,而是作为一个在代码发生添加或变更之后使用的工具。 Lint可以发现一些隐藏的bug并且可以在问题发生前保证程序的可移植性。lint产生的许多信息确实暗示了一些事情是错误的。一个有意思的故 事是关于一个漏掉了fprintf的一个参数的程序:

fprintf ("Usage: foo -bar <file>\n");

作者从未有过一个问题。但每当一个正常用户在命令行上犯错,这个程序就会产生一个core。许多版本的lint工具都能发现这个问题。

大多lint选项都值得我们学习。一些选项可能在合法的代码上给出警告,但它们也会捕捉到许多把事情搞遭的代码。注意'–p'只能为库的一个子 集检查函数调用和类型的一致性,因此程序为了最大化的覆盖检查,应该同时进行带–p和不带–p的lint检查。

Lint也可以识别代码里的一些特殊注释。这些注释可以强制让lint在发现问题时关闭警告输出,还可以作为一些特殊代码的文档。

20. Make

另外一个非常有用的工具是make。在开发过程中,make只会重新编译那些上次make后发生了改变的模块。它也可以用于自动化其他任务。一些 常见的约定包括:

all
执行所有二进制文件的构建过程

clean
删除所有中间文件

debug
构建一个测试用二进制文件a.out或debug

depend
制作可传递的依赖关系

install
安装二进制文件,库等

deinstall
取消安装

mkcat
安装手册

lint
运行lint工具

print/list
制作一个所有源文件的拷贝

shar
为所有源文件制作一个shar文件

spotless
执行make clean,并将源码存入版本控制工具。注意:不会删除Makefile,即便它是一个源文件。

source
撤销spotless所做的事情。

tags
运行ctags(建议使用-t标志)

rdist
分发源码到其他主机

file.c
从版本控制系统中检出这个文件

除此之外,通过命令行也可以定义Makefile使用的值(如"CFLAGS")或源码中使用的值(如"DEBUG")。

21. 工程相关的标准

除了这里提到内容外,每个独立的工程都期望能建立附加标准。下面是每个工程程序管理组需要考虑的问题中的一部分:

    * 哪些额外的命名约定需要遵守?尤其是,那些用于全局数据的功能归类以及结构体或联合体成员名字的系统化的前缀约定非常有用。

    * 什么样的头文件组织适合于工程特定的数据体系结构?

    * 应该建立什么样的规程来审核lint警告?需要确立一个与lint选项一致的宽容度,保证lint不会针对一些不重要的问题给出警告,但同时保证真正的bug或不一致问题不被隐藏。

    * 如果一个工程建立了自己的档案库,它应该计划向系统管理员提供一个lint库文件。这个lint库文件允许lint工具检查对库函数的兼容性使用。

    * 需要使用哪种版本控制工具?

22. 结论

这里描述了一套C语言编程风格的标准。其中最重要的几点是:

    * 合理使用空白和注释,使得我们通过代码布局就可以清楚地看出程序的结构。使用简单表达式、语句和函数,使他们可以很容易地被理解。

    * 记住,在将来某个时候你或其他人很可能会被要求修改代码或让代码运行在一台不同的机器上。精心编写代码,使得其可以移植到尚不确定的机器上。局部化你的优化,因为这些优化经常让人困惑,并且对于该优化措施是否适合其他机器我们持悲观态度。

    * 许多风格选择是主观武断的。保持代码风格一致比遵循这些绝对的风格规则更重要(尤其是与组织内部标准保持一致)。混用风格比任何一种糟糕的风格都更加糟糕。

无论采用哪种标准,如果认为该标准有用就必须遵循它。如果你觉得遵循某条标准时有困难,不要仅仅忽略它们,而是在和你当地的大师或组织内的有经验的程序员讨论后再做决定。

23. 参考资料

    1. B.A. Tague, C Language Portability, Sept 22, 1977. This document issued by department 8234 contains three memos by R.C. Haight, A.L. Glasser, and T.L. Lyon dealing with style and portability.
   
    2. S.C. Johnson, Lint, a C Program Checker, Unix Supplementary Documents, November 1986.
   
    3. R.W. Mitze, The 3B/PDP-11 Swabbing Problem, Memorandum for File, 1273-770907.01MF, September 14, 1977.
   
    4. R.A. Elliott and D.C. Pfeffer, 3B Processor Common Diagnostic Standards- Version 1, Memorandum for File, 5514-780330.01MF, March 30, 1978.

    5. R.W. Mitze, An Overview of C Compilation of Unix User Processes on the 3B, Memorandum for File, 5521-780329.02MF, March 29, 1978.

    6. B.W. Kernighan and D.M. Ritchie, The C Programming Language, Prentice Hall 1978, Second Ed. 1988, ISBN 0-13-110362-8.

    7. S.I. Feldman, Make — A Program for Maintaining Computer Programs, UNIXSupplementary Documents, November 1986.

    8. Ian Darwin and Geoff Collyer, Can't Happen or / NOTREACHED / or Real Programs Dump Core, USENIX Association Winter Conference, Dallas 1985
Proceedings.

    9. Brian W. Kernighan and P. J. Plauger The Elements of Programming Style. McGraw-Hill, 1974, Second Ed. 1978, ISBN 0-07-034-207-5.

    10. J. E. Lapin Portable C and UNIX System Programming, Prentice Hall 1987, ISBN 0-13-686494-5.

    11. Ian F. Darwin, Checking C Programs with lint, O'Reilly & Associates, 1989. ISBN 0-937175-30-7.

    12. Andrew R. Koenig, C Traps and Pitfalls, Addison-Wesley, 1989. ISBN 0-201-17928-8.
 




这里是Tony Bai的个人Blog,欢迎访问、订阅和留言!订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您喜欢通过微信App浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:



本站Powered by Digital Ocean VPS。

选择Digital Ocean VPS主机,即可获得10美元现金充值,可免费使用两个月哟!

著名主机提供商Linode 10$优惠码:linode10,在这里注册即可免费获得。

阿里云推荐码:1WFZ0V立享9折!

View Tony Bai's profile on LinkedIn


文章

评论

  • 正在加载...

分类

标签

归档











更多