Tag Archives: Code Style

再说说代码风格

老掉牙的话题了,晚上bb给我发一段 php代码,别人写的taobao api,要修改一下cache,我看了,头都大了,代码缩进tab与空格并用,导致我用vim打开很乱。一般,代码写得很糟糕的,我都拒绝看,老朋友嘛,硬着头皮看看,用indent对齐一下,还算好。再看一些函数的命名,我又晕了一把。比如
public function SendCheng ($mode = 'GET',$format = 'xml')
还真的看不明白是什么意思。

在小的软件公司,很多新员工来上班第一天,领导拷贝一堆pdf技术文档给你自个儿看,公司压根儿没编码规范的文档,祸害从此开始。从另一个侧面来说,作为一个程序员,自己也有责任去看《程序设计实践》,网上流传的《华为编码规范》,林锐的《高质量C/C++编程指南》等。千万不要搞什么像Button1, Button2, Button3, xingbie(性别), jifen(积分, 这个的命名方式,害人害己。美工A进公司时也已经工作3年了,网页与图片都是随便的001.html, 002.html, 003.index,不明白是什么意思。我问她为什么不给它们起个有意思的名字,比如一张表示团队的图片,teamwork,jpg 与001.jpg,谁更容易管理,更容易让搜索引擎找到?她说以前没人要求她这么做过,文件随意放,老师没教过要这样做的。再者,搞网站3年,竟然不知道什么是w3c,我真的感到悲哀,同时也为我自己感到悲哀,没有做这方面的测试,以为这是基本的知识,大家都知道了。

良好的代码风格,是一个程序员的基本修养。

一个封装 android.util.Log 的Log类

在android代码的每个Activity,都不厌其烦的写:

private static final String TAG = "MyActivity";

然后需要打印的地方输入:

Log.v(TAG, "index=" + i);

写太多的TAG,也麻烦,如果不写TAG,用 this.toString() 也可行,不过还是一样,于是写个包装Log类,自动处理是哪个Activity,调用哪个函数,如下:

/*
 * Copyright (C) 2010 Lytsing Huang http://lytsing.org
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.lytsing.android.util;

/**
 * Wrapper API for sending log output.
 */
public class Log {
    protected static final String TAG = "MyApplication";

    public Log() {
    }

    /**
     * Send a VERBOSE log message.
     * @param msg The message you would like logged.
     */
    public static void v(String msg) {
        android.util.Log.v(TAG, buildMessage(msg));
    }

    /**
     * Send a VERBOSE log message and log the exception.
     * @param msg The message you would like logged.
     * @param thr An exception to log
     */
    public static void v(String msg, Throwable thr) {
        android.util.Log.v(TAG, buildMessage(msg), thr);
    }

    /**
     * Send a DEBUG log message.
     * @param msg
     */
    public static void d(String msg) {
        android.util.Log.d(TAG, buildMessage(msg));
    }

    /**
     * Send a DEBUG log message and log the exception.
     * @param msg The message you would like logged.
     * @param tr An exception to log
     */
    public static void d(String msg, Throwable thr) {
        android.util.Log.d(TAG, buildMessage(msg), thr);
    }

    /**
     * Send an INFO log message.
     * @param msg The message you would like logged.
     */
    public static void i(String msg) {
        android.util.Log.i(TAG, buildMessage(msg));
    }

    /**
     * Send a INFO log message and log the exception.
     * @param msg The message you would like logged.
     * @param thr An exception to log
     */
    public static void i(String msg, Throwable thr) {
        android.util.Log.i(TAG, buildMessage(msg), thr);
    }

    /**
     * Send an ERROR log message.
     * @param msg The message you would like logged.
     */
    public static void e(String msg) {
        android.util.Log.e(TAG, buildMessage(msg));
    }

    /**
     * Send a WARN log message
     * @param msg The message you would like logged.
     */
    public static void w(String msg) {
        android.util.Log.w(TAG, buildMessage(msg));
    }

    /**
     * Send a WARN log message and log the exception.
     * @param msg The message you would like logged.
     * @param thr An exception to log
     */
    public static void w(String msg, Throwable thr) {
        android.util.Log.w(TAG, buildMessage(msg), thr);
    }

    /**
     * Send an empty WARN log message and log the exception.
     * @param thr An exception to log
     */
    public static void w(Throwable thr) {
        android.util.Log.w(TAG, buildMessage(""), thr);
    }
    
    /**
     * Send an ERROR log message and log the exception.
     * @param msg The message you would like logged.
     * @param thr An exception to log
     */
    public static void e(String msg, Throwable thr) {
        android.util.Log.e(TAG, buildMessage(msg), thr);
    }

    /**
     * Building Message
     * @param msg The message you would like logged.
     * @return Message String
     */
    protected static String buildMessage(String msg) {      
        StackTraceElement caller = new Throwable().fillInStackTrace().getStackTrace()[2];

         return new StringBuilder()
                .append(caller.getClassName())
                .append(".")
                .append(caller.getMethodName())
                .append("(): ")
                .append(msg).toString();
    }
}

LogDemo.java:

package org.lytsing.android.log;

import org.lytsing.android.util.Log;
import android.app.Activity;
import android.os.Bundle;

public class LogDemo extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        
        Log.i("index=" + 3);
    }
}

运行结果的Log信息,如下图:

需要的话,懒得复制粘贴,可以下载Log.java压缩文件包Log.tar.gz

此外Android 代码风格指南 特别说明了,日志记录开销很大,应尽量少用,写规范可靠的代码,减少对debug的依赖。

Android 代码风格指南

翻译状态: 完成进度82%

本文的英文原始文档(Android Code Style Guidelines for Contributors)地址 : http://source.android.com/source/code-style.html

国内用户如果无法直接访问,请自行翻墙。第一次翻译Java类的文档, 如果有差错和不妥之处, 请不吝指出.

Android的代码风格规则

The rules below are not guidelines or recommendations, but strict rules. Android代码贡献者,如果他们不遵守这些规则,那么一般他们的代码不会被接受
并非所有现存的代码遵循这些规则,但所有的新代码希望能如此

Java 语言规则

我们遵循标准的Java编码约定。
我们还添加一些规则:
  1. 异常:不要在没有说明的情况下捕捉和忽略它们。
  2. Exceptions : 不要捕捉一般异常, except in library code at the root of the stack.
  3. Finalizers :一般不使用它们。
  4. Imports : 完全符合引入

Java库规则

这里有一些关于使用android Java库与工具的约定。在某些情况下,该约定在一些重要的方式已经发生了变化,老的代码可能在使用过时的模式或库。当使用这些代码,最好继续保持与已存在的风格一致(参见一致性)当创建新的组件从来不使用废弃库。

Java的风格规则

当所有文件都保持一致的风格时,程序就更容易维护。我们遵循标准的Java编码风格,他们由Sun公司为Java编程语言制定的编码约定,除少数例外,和增加一些。这些风格指南是全面而详细的,在Java社区很常用。

此外,我们执行下面的样式规则:
  1. 注释/Javadoc :使用标准样式写它
  2. 简短的方法 :不写超大的方法
  3. 字段(成员变量):要么是在该文件的顶部,或紧接在使用它们的方法前面。
  4. 局部变量 :限制作用域
  5. 引入 :android;第三方按字母顺序排列;java(x)
  6. 缩进排版 :4个空格,没有制表符(tab)
  7. 行长度 :100个字符
  8. 字段命名 : 非公有的,非静态字段以m开头,静态变量以s开头 。
  9. 括号 :开括号不要独占一行
  10. 注解 :使用标准的注解。
  11. Acronyms are words : Treat acronyms as words in names, yielding XmlHttpRequest , getUrl() , etc.
  12. TODO的风格 :“TODO:在这里写描述”
  13. 一致性 :看看你周围的
  14. 日志记录 :小心日志记录,它开销很大。

Javatests样式规则

1. 测试方法的命名 :testMethod_specificCase是正确的