Чистый код. Создание, анализ и рефакторинг (Мартин) - страница 48
> }
> private void includePageContent() throws Exception {
> newPageContent.append(pageData.getContent());
> }
> private void includeTeardownPages() throws Exception {
> includeTeardownPage();
> if (isSuite)
> includeSuiteTeardownPage();
> }
> private void includeTeardownPage() throws Exception {
> include("TearDown", "-teardown");
> }
> private void includeSuiteTeardownPage() throws Exception {
> include(SuiteResponder.SUITE_TEARDOWN_NAME, "-teardown");
> }
> private void updatePageContent() throws Exception {
> pageData.setContent(newPageContent.toString());
> }
> private void include(String pageName, String arg) throws Exception {
> WikiPage inheritedPage = findInheritedPage(pageName);
> if (inheritedPage != null) {
> String pagePathName = getPathNameForPage(inheritedPage);
> buildIncludeDirective(pagePathName, arg);
> }
> }
> private WikiPage findInheritedPage(String pageName) throws Exception {
> return PageCrawlerImpl.getInheritedPage(pageName, testPage);
> }
> private String getPathNameForPage(WikiPage page) throws Exception {
> WikiPagePath pagePath = pageCrawler.getFullPath(page);
> return PathParser.render(pagePath);
> }
> private void buildIncludeDirective(String pagePathName, String arg) {
> newPageContent
> .append("\n!include ")
> .append(arg)
> .append(" .")
> .append(pagePathName)
> .append("\n");
> }
>}
Литература
[KP78]: Kernighan and Plaugher, The Elements of Programming Style, 2d. ed., McGraw-Hill, 1978.
[PPP02]: Robert C. Martin, Agile Software Development: Principles, Patterns, and Practices, Prentice Hall, 2002.
[GOF]: Design Patterns: Elements of Reusable Object Oriented Software, Gamma et al., Addison-Wesley, 1996.
[PRAG]: The Pragmatic Programmer, Andrew Hunt, Dave Thomas, Addison-Wesley, 2000.
[SP72]: Structured Programming, O.-J. Dahl, E. W. Dijkstra, C. A. R. Hoare, Academic Press, London, 1972.
Глава 4. Комментарии
Не комментируйте плохой код — перепишите его.
Брайан У. Керниган и П. Дж. Плауэр[21]
Ничто не помогает так, как уместный комментарий. Ничто не загромождает модуль так, как бессодержательные и безапелляционные комментарии. Ничто не приносит столько вреда, как старый, утративший актуальность комментарий, распространяющий ложь и дезинформацию.
Комментарии — не список Шиндлера. Не стоит относиться к ним как к «абсолютному добру». На самом деле комментарии в лучшем случае являются неизбежным злом. Если бы языки программирования были достаточно выразительными или если бы мы умели искусно пользоваться этими языками для выражения своих намерений, то потребность в комментариях резко снизилась бы, а может, и вовсе сошла «на нет».