【1414软工助教】在博客中插入代码

在已经发布的和将来要发布的作业中，都会要求同学们贴出程序中的关键代码。

从目前提交的作业来看，主要有三个的问题：

  1. 有的同学不知道怎么在Markdown的编辑器里插入代码，导致发布之后代码没有缩进。这些代码难以阅读。
  2. 在贴出代码的同学中，有一部分将不是关键代码的部分也贴出来。这样代码占了博客中的大部分内容，而且很多都是没用的信息。
  3. 没有注意代码规范，大量使用单字符无意义变量，例如 i,j,k,n,m（看得我很难受……）

如何在Markdown里正确地插入代码

在Markdown中，使用一对 ``` 来围住代码。注意，这里的点是键盘左上角1左边的那个按键。如下图：


图片截取自京东：http://item.jd.com/1914332.html

还要注意的一点是，输入法必须在英文状态下才能输入这种点 ` ，如果是中文状态，那么就会变成 · 。下面是一个例子：

```java
@DatabaseTable(tableName = "tb_def")
public class Word {
    @DatabaseField(generatedId = true, columnName = COLUMN_ID)
    private int id;
    @DatabaseField(columnName = COLUMN_WORD)
    private String word;
    @DatabaseField(columnName = COLUMN_SUGGESTION)
    private String suggestion;

    public static final String COLUMN_ID = BaseColumns._ID;
    public static final String COLUMN_WORD = SearchManager.SUGGEST_COLUMN_TEXT_1;
    public static final String COLUMN_SUGGESTION = SearchManager.SUGGEST_COLUMN_INTENT_DATA;
    
    ...
    
    public Word(int id, String word, String suggestion) {
    this.id = id;
    this.word = word;
    this.suggestion = suggestion;
    }
    
    ...
}
```

第一行的三个点后面写了java，这里告诉解析器“这里围起来的代码是JAVA代码，请使用JAVA的代码高亮方式显示”，以下是效果：

@DatabaseTable(tableName = "tb_def")
public class Word {
    @DatabaseField(generatedId = true, columnName = COLUMN_ID)
    private int id;
    @DatabaseField(columnName = COLUMN_WORD)
    private String word;
    @DatabaseField(columnName = COLUMN_SUGGESTION)
    private String suggestion;

    public static final String COLUMN_ID = BaseColumns._ID;
    public static final String COLUMN_WORD = SearchManager.SUGGEST_COLUMN_TEXT_1;
    public static final String COLUMN_SUGGESTION = SearchManager.SUGGEST_COLUMN_INTENT_DATA;
    
    ...
    
    public Word(int id, String word, String suggestion) {
    this.id = id;
    this.word = word;
    this.suggestion = suggestion;
    }
    
    ...
}

在博客园中，你会发现跟上面两个版本都有代码高亮。这应该是博客园的问题，第一个版本其实在Visual Studio Code中的显示效果是字母全都白色。

注意！请同学们在发布博客之后，从头到尾检查一遍自己的博客，看排版上是否有问题。如果有问题请尽快改过来。

只展示关键的代码

如果你想保持完整的结构，可以像上面作为示例的代码那样。把无关的地方删掉，并使用三个点...代替。这三个点也是英文的，但按键的位置在中文的句号那里。

示例代码是我一篇博客中的一个展示：嵌入AppBar并且带搜索建议的搜索框（Android）

除此之外，你也可以不用像示例代码那样保持完整的结构。在博客中以文字为主，在必要的情况下添加几行代码，对代码进行解释。

展示的代码应让读者对你所想要说明的东西有一个直观的感受，把太多无关的代码放进去会分散读者的注意力。

代码规范

你可以自己到网上去找代码规范。以下是一些供参考链接：

如果你想最直观地体验“阅读别人的不规范代码”是一种什么样的感受，可以：

  1. 拿出你大一大二写的代码，并尝试在短时间内看懂这些代码是干嘛的
  2. 等过个一两周再回来看看你现在写的这些代码，看看你是否还能很快看懂

最后，附上漫画：

程序员的日常：哪个蠢蛋写的烂代码？

图片引用自：http://codingpy.com/article/programmers-daily-what-idiot-wrote-this-crappy-code/

posted @ 2017-03-04 23:08  schaepher  阅读(1189)  评论(2)  编辑  收藏  举报