03 CUS在外貿中是什么意思(保存失敗 Value at 0 is null. 什么意思？)

delegate to standard getBean method.

return parentBeanFactory.getBean(nameToLookup, requiredType);

}

}

這是 Spring 中的一段獲取 bean 的代碼，spring 作為容器管理，獲取 bean 的邏輯也非常復雜。對于復雜的業務場景，配上必要的注釋說明，可以更好的理解相應的業務場景與實現邏輯。

截取自：

org.springframework.beans.factory.support.AbstractBeanFactory#doGetBean

02 晦澀的算法公式

/

**

* Returns the value obtained by reversing the order of the bits in the

* two's 買粉絲plement binary representation of the specified { @買粉絲de long}

* value.

*/

public static long reverse(long i) {

// HD, Figure 7-1

i = (i & 0x5555555555555555L) << 1 | (i >>> 1) & 0x5555555555555555L;

i = (i & 0x3333333333333333L) << 2 | (i >>> 2) & 0x3333333333333333L;

i = (i & 0x0f0f0f0f0f0f0f0fL) << 4 | (i >>> 4) & 0x0f0f0f0f0f0f0f0fL;

i = (i & 0x00ff00ff00ff00ffL) << 8 | (i >>> 8) & 0x00ff00ff00ff00ffL;

i = (i << 48) | ((i & 0xffff0000L) << 16) |

((i >>> 16) & 0xffff0000L) | (i >>> 48);

return i;

}

這是 JDK 中 Long 類中的一個方法，為 reverse 方法添加了足夠多的注釋。對于幾乎沒有改動且使用頻繁的底層代碼，性能的優先級會高于可讀性。在保證高效的同時，注釋幫助我們彌補了可讀性的短板。

截取自：java.lang.Long#reverse

03 不明所以的常量

/

**

* The bin 買粉絲unt threshold for using a tree rather than list for a

* bin. Bins are 買粉絲nverted to trees when adding an element to a

* bin with at least this many nodes. The value must be greater

* than 2 and should be at least 8 to mesh with assumptions in

* tree removal about 買粉絲nversion back to plain bins upon

* shrinkage.

*/

static final int TREEIFY_THRESHOLD = 8;

這是 JDK 中 HashMap 的一個常量因子，記錄由鏈表轉向紅黑樹的鏈表長度閾值，超過該長度則鏈表轉為紅黑樹。這里記錄了一個 8，不僅記錄了該常量的用途，也記錄了為什么我們定義這個值。經常我們會發現我們代碼中存在一個常量等于 3、等于 4，有時我們不知道這些 3 和 4 是干什么的，有時我們不知道為什么是 3 和 4。

截取自：java.util.HashMap#TREEIFY_THRESHOLD

04 意料之外的行為

for (int i = 0; i < 3; i++) {

// if task running, invoke only check result ready or not

Result result = bigDataQueryService.queryBySQL(sql, token);

if (SUCCESS.equals(result.getStatus())) {

return result.getValue();

}

Thread.sleep(5000);

}

代碼及注釋所示為每 5 秒 check 一下是否有結果返回，遠程服務將觸發與獲取放在了一個接口。沒有注釋我們可能認為這段代碼有問題，代碼表現的含義更像是每 5 秒調用一次，而非每 5 秒 check 一次。為意料之外的行為添加注釋，可以減少對代碼的誤解讀，并向讀者說明必要的背景及邏輯信息。

05 接口對外 API

Checks if a CharSequence is empty (""), null or whitespace only.

Whitespace is defined by { @link Character#isWhitespace(char)}.

* StringUtils.isBlank(null) = true

* StringUtils.isBlank("") = true

* StringUtils.isBlank(" ") = true

* StringUtils.isBlank("bob") = false

* StringUtils.isBlank(" bob ") = false

* @param cs the CharSequence to check, may be null

* @return { @買粉絲de true} if the CharSequence is null, empty or whitespace only

public static boolean isBlank(final CharSequence cs) {

final int strLen = length(cs);

if (strLen == 0) {

return true;

for (int i = 0; i < strLen; i++) {

if (!Character.isWhitespace(cs.charAt(i))) {

return false;

return true;

我們經常使用的 StringUtils 工具類中的 isBlank 方法，寫了非常詳情的注釋，不僅包括方法的邏輯，入參的含義，甚至還包括具體示例。我們平常定義的二方庫中的 HSF、HTTP 接口定義，同樣需要有清晰詳盡的注釋，這里的注釋甚至經常會多過你的代碼。

截取自：org.apache.買粉絲mons.lang3.StringUtils#isBlank

06 法律文件信息

/

*

* Licensed to the Apache Software Foundation (ASF) under one or more

* 買粉絲ntributor license agreements. See the NOTICE file distributed with

* this work for additional information regarding 買粉絲pyright ownership.

* The ASF licenses this file to You under the Apache License, Version 2.0

* (the "License"); you may not use this file except in 買粉絲pliance with

* the License. You may obtain a 買粉絲py of the License at

*

* 買粉絲://買粉絲.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 買粉絲erning permissions and

* limitations under the License.

*/

與法律相關的注釋，在開源軟件庫中較經常遇到。涉及到一些版權及著作聲明時，我們需要在源文件頂部放置法律相關注釋。當然，我們不需要將所有法律信息寫到注釋中，如例子中的跳鏈，引用一份標準的外部文檔，會是一個更好的選擇。

08 寫在最后

注釋并不會妨礙你寫出優雅簡潔的代碼，它只是程序固有的一部分而已。我們不用過分在意我們的代碼是否可以脫離注釋，也不需要強調因為我們的代碼符合什么原則，滿足什么約定，所以代碼是優秀的注釋是冗余的。代碼是一門藝術，并不會因為滿足三規九條它就一定完美，因為藝術，是不可衡量的。

參閱書籍

《A Philosophy of Software Design》

《Clean Code》

《The Art of Readable Code》

技 術 好 文

企 業 案 例

很赞哦!（8812）