0 目的(purpose)
Qiitaに投稿する自分のまたは引用したソースコードの書式(style)に一貫性を持たせることにより、読みやすく、誤解が生じにくくすることを目的とする。
成果(outcome)
国際規格、コーディング標準などのコード断片を引用しており、
これらの文書との整合性をどのように取ると良いかの考えが整理できる。
背景(background)
QiitaにC, C++のプログラムを投稿していて、
自分でも分かりにくいことが多々ある。
予定(schedule)
Styleの代表例を作ってみる。
自分が全部描く場合は、なるべく代表例に沿い、
他のプログラムを引用して追記する場合には、
追記する部分を代表例に従うことにする。
現在あげているソースは順次、この書式に近い形式に変更して行く。
今後あげるソースで、この書式では不十分な場合は、この書式を変更する。
1 前段(introduction)
1.1 著作権(copyrightt)または著者(author)
個人、または団体名を記載する。
自分が試験用に追記した部分は、当面///で始まるコメント行とする。
ただし、引用したソースが///で始まるコメント行を利用している場合には、別の方法を検討する。
1.2情報源(information source)
本またはネットに公開されているソースは、書名またはURLを記載する。ページ数のある冊子の場合はなるべくページ数を記載する。
1.3 目的(purpose)と成果(outcome)
何のためのプログラムでどういう成果があるかを記載する。
国際規格、コーディング規則の場合は、章節名、実行結果の記載で代替することがある。
国際規格、コーディング規則は、立場によって見え方が違い、目的と成果もそれぞれである。目的と成果を議論したい場合以外は、記載しない。
1.4 系(system)
編纂器(compiler)
コンパイラの名称と版を記載する。
環境(environment)
C言語の場合は、hosted, freestaningの区別と、実行結果を記録した環境名を記載する。
台本(script)
複数の編纂器を利用する台本などを記載する。
実行結果にURLを記載することで代替することがある。
整形は台本a.shを使う。
第二部 算譜(code)
2.1 ヘッダファイル
必要最小限のヘッダをincludeする。
試験作業の効率上、最終的には不要になるヘッダファイルが残っていることがある。
該当するCソースファイルに固有なヘッダファイルを作ることがある。
また、国際規格、コーディング標準に共通のヘッダファイルを作ることがある。
2.2 定数・変数・マクロ宣言・ファイル
必要最小限の定数、変数、マクロ宣言とする。
定数の値、文字変数の値、ファイルの値などは、
そのソースコードファイルおよび記述を利用することがある。
例えば、ファイル読み込みは、指定がなければ、ソースコードファイルを読み込む。
2.3 出力(output)
必要最小限の出力とする。
条件分岐の結果がわかるような出力を追記することがある。（printf debug, cout debug)
暴走するのを防いだり、処理時間を確認するための出力を記載することがある。
出力が必要でない処理の場合は、表題・ファイル名等を出力することがある。
字下げ(indentation)
字下げは2文字を原則とする。
Web上で見る場合に、折り返しがなるべく少なくするためである。
#!/bin/bash
astyle -s2 -c -N < $1.cpp > $1s2.cpp
cat $1s2.cpp
命名規則(naming convention)
定数名(constant name)
定数名は大文字だけを原則とする。
英語で意味のある名前とする。場合によっては日本語のローマ字表記相当の場合もある。
変数名(variable name)
変数名は小文字だけを原則とする。
ループ変数のi,j,k、簡単な計算の変数、a,b,c,x,y,z、文字列のs,文字のcなどの１文字変数を使うことがある。
関数名(function name)
関数名は小文字だけを原則とする。
簡単な処理をする関数は、f,g,h等の１文字関数を使うことがある。
startup 関数
C言語のhosted環境の場合は、
int main(int argc, char * argv[]);
int main(void)
void main(void)
といずれかとする。
C言語のfreestanding環境の場合は
void startup(void);
void startup(int argc);
void startup(char * argv[]);
int startup(void);
など、その時々の必要に応じて記述する。
hosted環境と同じプログラムを実行する場合の名前は
mainのままとすることがある。
この場合には、freestanding環境のstartup関数の別名としてmainを定義するか、リンクスクリプトでmainをstartupに変換するかはその時々とする。
startup関数に引数、戻り値がある場合には、startup関数手を入れる場合がある。
単純な例として、引数の数を引数とし、引数の数の値を戻り値として、実行中に値に変更が加わっていないかを確かめるのに用いる。
出力機構(output mechanism)
C言語のfreestanding環境においてC言語のhosted環境と同じソースをコンパイルする場合は、ヘッダファイルのマクロにおいて、printf関数をfreestanding環境における出力関数に置き直すことがある。
C++のhosted環境においてはcoutを
using namespace std;
を宣言して利用する。
第三部 結果(result)
3.1 誤(error)、警告(warning)
オプションをつけない場合を記録する。
C89(ISO/IEC9899:1990), C1999, C2011対応の場合、
C++(ISO/IEC 14882:1998,C++2003, C++2011, C++2014, C++2017対応の場合には、
それぞれの版のオプションをつけることがある。
3.2 実行結果(execution result)
コンパイルエラーで実行できない場合以外は実行結果をつける。
暴走したり、画面に何も表示せずに、数分立っても終わらない場合はその旨を記載する。
例(example)
// ISO/IEC JTC 1/SC 22/WG 14 N 1624 Date: 2012-06-26 ISO/IEC TS 17961, p.7
/// lines are added by Dr. Kiyoshi Ogawa, 2018
/// Compiled on
/// Clang(LLVM) clang version 6.0.0 (tags/RELEASE_600/final)
/// GCC(GNU) gcc-7 (Homebrew GCC 7.3.0_1) 7.3.0
/// hosted Environment macOS 10.13.3 or 10.12.9
// EXAMPLE 1 In this noncompliant example, a diagnostic is required because head->next is accessed after head has been freed.
#include <stdio.h>/// for printf
#include <stdlib.h>/// for EXIT_SUCCESS
struct List { struct List *next; /* ... */ };
void free_list(struct List *head) {
for (; head != NULL; head = head->next) { // diagnostic required
printf("%ld %ld \n",(long)head, (long)head->next);
free(head);
}
}
int main(int argc, char** argv){///
struct List *lista;///
size_t sz = sizeof(struct List);///
lista = malloc(sz);///
lista->next = NULL;///
printf("%ld \n",(long)lista);///
free_list(lista);///
return EXIT_SUCCESS;///
}///
$ ./gcc7ts.sh accfree
$ clang accfree.c
140206166508352
140206166508352 0
$ gcc-7 accfree.c
140691146539008
140691146539008 0
参考資料(reference)
コンパイル用shell script C版(clangとgcc)とC++版(clang++とg++)
https://qiita.com/kaizen_nagoya/items/74220c0577a512c2d7da
文書履歴(document history)
ver 0.10 初稿 20180407
ver 0.11 C++追記 20180408
ver 0.20 整形台本追記 20180524
＜この記事は個人の過去の経験に基づく個人の感想です。現在所属する組織、業務とは関係がありません。＞
最後までおよみいただきありがとうございました。
いいね 💚、フォローをお願いします。
Thank you very much for reading to the last sentence.
Please press the like icon 💚 and follow me for your happy life.