Java Coding Style 內的 at-clauses 是什麼意思?

今天下午在龍潭某半軍事院所教授「軟體結構設計」系列課程,案例主要以 Java/Spring 來實作。

課後結束,該單位一位單純又可愛的年輕正妹送我出門 (視為廠商單位需內部人員陪同檢查證件),然後順便在會客室就近問我些問題 (好認真有心的女孩呢,假日還會窩在住宿處練習寫碼我提供的實作案例,值得肯定鼓勵)。

不過她問的問題反而不是我課堂教授的內容,是針對 Java Coding Style 某一部份的定義她不太了解。

啊,我極少重視這種所謂 "Coding Style" 議題,大概也只是縮行、空白行,盡量讓 method name、參數、回傳值等給予有意義的命名,整個敘述讀起來通順即可。

不過大型單位會要求這些也不是沒道理,總還是希望有所謂共同的寫碼基本規範 (不過反而沒要求 Method 陳述要控制在 30 行以內,這點期望能加進去)。

嗯,她問我的問題是 :
當全部的「at-clauses 」都出現時,其標準的使用順序為 @param 、 @return 、 @throws 、 @deprecated ,而這四種類型都不會為空。當一個「at-clauses」無法以單行描述完畢時,其續行該要以 @ 為基準做四個(或更多)空白的縮排。

這,當下我肯定不會,所以承諾她說晚上回家找我的好哥們請教。然後就剛沒多久,問我那位哥們不到 10 分鐘就給出範例答案啦。

/**
 * Subject line
 *
 * <p>Description of the method with optional {@code code} and {@link Object links to Javadoc}
 * </p>
 *
 * <pre>
 *    raw input
 * </pre>
 *
 * @param foo first arg
 * @return a bar
 * @throws SomeException if bar goes wrong
 * @see someOtherMethod()
 * @since 2.2.2
 * @author me
 */
int doSomething(final int foo)
    throws SomeException
{
    // etc
}

另外,@deprecated 的寫法:

/**
 * This method use a deprecated API
 *
 * @deprecated use {@link #newMethodNodeprecated()} instead.  
 */
@Deprecated
public void oldMethod() {
// ...
}

我這哥們怎麼這麼厲害?!哈,他可是無所不知、無所不曉啊~。只要是這類 "How-to" 問題,問他肯定有答案的。

這哥們可是很願意與任何人當好朋友,提供解答的。只是太多人不懂得珍惜,也不懂得如何與之當好朋友,所以常要求自己硬記容易發散不實用的工具使用與各大廠商規定的遊戲規則等,久而久之,腦袋反而不會柔軟卻是更形僵化了,殊為可惜啊。

文章導覽

 

發表迴響

你的電子郵件位址並不會被公開。 必要欄位標記為 *