Documentation of Standard Typing Rules
Scope Of Document
Scope of This Document
This document is a standard typing for code that applies only to markup/programming language training conducted by Mineversal. Precautions When engaging in development work in a different environment, it is necessary to comply with the coding standards determined for each site.
What Are Coding Conventions
A coding standard is a document that stipulates “rules for writing” when creating program code. By prescribing coding rules in advance, the aim is to make it easy for anyone to see (unification) and to eliminate potential defects (elimination of mistakes). In addition, even if you want to automatically process program code at once, such as a check tool or a conversion tool, you can expect the advantage that it is less likely to cause trouble if the program complies with coding standards.
Standard Typing Code
NUMBER OF CHARACTERS PER LINE
The maximum number of characters per line is 100 (double-width characters such as kanji are counted as two digits).
INDENTATION
Tabs are used for indentation, and the number of characters in the tabs is 4. Instead of tabs, no spaces shall be filled. Note: “Notepad” is only for 8 characters, so it will not be 4 characters.
The description of blocks (units from { to }) is as shown in the following example, and the syntax is described after indentation.
Example:
for ( i = 0; i < MSG_MAX; i++ )
{
[Tab]<Syntax>
[Tab]<Syntax>
}
Other example:
if ( langId == LANG_EN )
{
[Tab]<Syntax>
}
else if ( langId == LANG_ID )
{
[Tab]<Syntax>
}
In the case of nested states where blocks are created within blocks, further indent the area enclosed by { }.
bool fs_tf_analizeFileUpCommand( char *cmd, int size )
{
[Tab]int i;
[Tab]for( i = 0; i < size; i++ )
[Tab]{
[Tab][Tab]<Syntax>
[Tab][Tab]<Syntax>
[Tab]}
[Tab]return OK_CMD;
}
Even if the block is a single statement and { } can be omitted, enclose it in { }.
if( filePtr == null )
{
[Tab]return ERR_CMD;
}
COMMENTS
In the code you create, be sure to write comments that do not rely on memory or knowledge, assuming that “others will see” or “maintain them yourself when you forget them in a few years.” It is desirable that comments and internal design documents are linked. Even if an internal design document does not exist, try to write at a “text” level that is sufficient for internal design documents with only comments.
Comments in different programming languages vary quite a bit but are generally begin with /* and end with */. Nesting is not allowed.
playTime = 0; /* Initialize playing time */
To comment out an entire line, use #if0 ~ #endif. In this case, /* if 0 */ should be added as a comment to indicate what the #endif corresponds to. Also, insert a // at the beginning of the commented out line so that you can instantly recognize it as a comment just by looking at the line (when greping).
Note: There are some sites where inserting // is bad (a large number of // are hit in the process of searching for the division part and visually checking), so in that case, set it to @.
#if 0 /* Temporarily suspend random play mode */
// case RANDOM_PLAYMODE: /* Random playing mode */
// mp3Player.RandomPlay();
// break;
#endif /* if 0 */
By the way, in C++, // can be used to comment out lines. It is not compatible with C and cannot be used in C.
// Temporary < Random play mode is suspended>
// case RANDOM_PLAYMODE: /* Random playing mode */
// mp3Player.RandomPlay();
// break;
FORMULA
Expressions should be separated by spaces (spaces) for easy viewing. Follow the example and code with spaces.
for( i = 0; i < MAX_LOOP_NUM; i++ )
{
[Tab]if( ChgFileName() != TRUE )
[Tab]{
[Tab][Tab]break;
[Tab]}
[Tab]else
[Tab]{
[Tab][Tab]fileSize = GetFileSize( INDEX_FIRST, INDEX_LAST ) + 256;
[Tab]}
}
HEADER RULES
Make sure after creating the files always insert comments as a header regarding the detailed description of the file at the top of the file, the format can be copied below:
Mark Up Languages (like HTML, MD, etc.):
<!---------------------------------------------------------------------------------------------->
<!-- [TITLE (USE THE CAPITAL ALPHABET)] -->
<!---------------------------------------------------------------------------------------------->
<!-- Copyright (C) 2020 MINEVERSAL -->
<!-- Licensed material of MINEVERSAL -->
<!---------------------------------------------------------------------------------------------->
<!-- Object : [Abbreviation of Title] -->
<!-- Outline : [A brief description of the files] -->
<!-- File ID : [Project Name-Object-Number Of FIles] -->
<!---------------------------------------------------------------------------------------------->
<!-- Author : [Your Name] -->
<!-- Revision Author : [Name of Revision Author] -->
<!-- Created Time : [Date Time (Your Global Time Location)] -->
<!-- Modification Time : [Date Time (Your Global Time Location)] -->
<!-- Version : 0 (Number of Version) -->
<!-- Revision : 0 (Number of Revision) -->
<!---------------------------------------------------------------------------------------------->
Programming Languages:
C:
/******************************************************************************/
/* [TITLE (USE THE CAPITAL ALPHABET)] */
/*----------------------------------------------------------------------------*/
/* Copyright (C) 2020 MINEVERSAL */
/* Licensed material of MINEVERSAL */
/*----------------------------------------------------------------------------*/
/* Object : [Abbreviation of Title] */
/* Outline : [A brief description of the files] */
/* File ID : [Project Name-Object-Number Of FIles] */
/*----------------------------------------------------------------------------*/
/* Author : [Your Name] */
/* Revision Author : [Name of Revision Author] */
/* Created Time : [Date Time (Your Global Time Location)] */
/* Modification Time : [Date Time (Your Global Time Location)] */
/* Version : 0 (Number of Version) */
/* Revision : 0 (Number of Revision) */
/******************************************************************************/
Python:
#####################################################################
# Python Programming Course #
#-------------------------------------------------------------------#
# Copyright (C) 2023 BINUS CENTER #
# Licensed material of BINUS #
#-------------------------------------------------------------------#
# Object : First_CLass #
# Outline : Introduction to the Programming with Python #
# File ID : PPC1 #
#-------------------------------------------------------------------#
# Author : Azhar Rizki Zulma #
# Revision Author : - #
# Created Time : 2023/11/5 10,00 (UTC+07:00) #
# Modification Time : - #
# Version : 1 #
# Revision : 0 #
#####################################################################
Note: If there are more than one author, separate them with commas.
HISTORY RULES
If there are updated version in the code file you must add this note.
Markup Languages:
<!------------------------------------------------------------------------------------------------->
<!-- History: -->
<!-- [Version] [Update Notes/Function Name] -->
<!-- [Version] -->
<!-- [Update Notes/Function Name] -->
<!-- [Update Notes/Function Name] -->
<!-- [Update Notes/Function Name] -->
<!------------------------------------------------------------------------------------------------->
Programming Languages:
C:
/******************************************************************************/
/* History: */
/* 0000-a 新規作成 */
/* O02-0000-a */
/* FSチームからの要求対応 */
/* fg_watch_hibktrq_INIT_1 */
/* fs_watch_hibktrq_1_EXEC */
/* μ取得関数の不具合修正 */
/* fs_u2_get_mu2_1 */
/* O03-0000-a */
/* 8速→6速化対応 */
/* fg_u1_hibktrq_ctrl_start */
/* fs_tf_app_element_cnt */
/* fs_u1_calc_hbt_engage_element */
/******************************************************************************/
Python
#####################################################################
# History: #
# Version-0 New File #
# Version-0.1 #
# Add User Requirement #
# fs_tf_inputData #
# fs_tf_outputData #
# Version-1 #
# Add User Requirement #
# fs_tf_deleteData #
# Version-1.0.1 #
# Add User Requirement #
# fs_tf_updateData #
#####################################################################
PACKAGES & LIBRARIES
If there are import libraries or packages use these comments above them as a header:
/******************************************************************************/
/* INCLUDE HEADER */
/******************************************************************************/
/******************************************************************************/
/* INCLUDE PACKGES */
/******************************************************************************/
/******************************************************************************/
/* IMPORT PACKGES */
/******************************************************************************/
If there is a define then use the header below:
/******************************************************************************/
/* PRIVATE DEFINITION */
/******************************************************************************/
/******************************************************************************/
/* PRIVATE TYPE DEFINITION */
/******************************************************************************/
If there is a constant, global or static variable declaration, make sure to comment a description as a header before declaring a global or static variable, the format can be checked below:
/******************************************************************************/
/* GLOBAL VALIABLE */
/******************************************************************************/
/******************************************************************************/
/* PRIVATE VARIABLE */
/******************************************************************************/
/******************************************************************************/
/* CONSTANT DATA */
/******************************************************************************/
/******************************************************************************/
/* CONSTANT VARIABLE */
/******************************************************************************/
Dont forget when declaring a class or function, always provide a description of the type of function or class above it with a comment like this as a header:
/***** PUBLIC CLASS ***********************************************************/
/***** PRIVATE CLASS **********************************************************/
/***** PUBLIC FUNCTION ********************************************************/
/***** PRIVATE FUNCTION *******************************************************/
If there are other cases, you can still use the header with the format below as a description:
/******************************************************************************/
/* [CASE NAME] */
/******************************************************************************/
Other example header:
/******************************************************************************/
/* PRIVATE PROTOTYPE DECLARATION */
/******************************************************************************/
/******************************************************************************/
/* AUTO TIMER */
/******************************************************************************/
Header for markup languages:
<!---------------------------------------------------------------------------------------------->
<!-- HEAD TAG -->
<!---------------------------------------------------------------------------------------------->
<!---------------------------------------------------------------------------------------------->
<!-- BODY TAG -->
<!---------------------------------------------------------------------------------------------->
And dont forget to add detail the function/class description above the function/class declaration, the format can be copied below:
CLASS:
/******************************************************************************/
/* Class: */
/* [Name of Class] */
/* Outline: */
/* [A brief description of the class] */
/* Class Explanation: */
/* [A brief description of the class and its uses] */
/* Note: */
/* [Class related notes] */
/* Traceability Reference ID: */
/* [The class relationship with other files is filled with */
/* explanations and descriptions and attaches an ID file] */
/******************************************************************************/
FUNCTION:
/******************************************************************************/
/* Function: */
/* [Name of Function] */
/* Outline: */
/* [A brief description of the function] */
/* Parameter: */
/* [Name of Parameter Variable] */
/* Return Value: */
/* [Name of Return Variable] */
/* Function Explanation: */
/* [A brief description of the function and its uses] */
/* Note: */
/* [Function related notes] */
/* Traceability Reference ID: */
/* [The functional relationship with other files is filled with */
/* explanations and descriptions and attaches an ID file] */
/******************************************************************************/
If there is a sub-description in the function, you can use the header description below:
/*-----------------------*/
/* [CASE FLOW] */
/*-----------------------*/
YOUR CODE
And if you want to provide a description of the above code use this:
/* description */
YOUR CODE
If you want to provide a description beside the code use this:
YOUR CODE // description
Provide description for markup languages:
<!-- TITLE -->
YOUR CODE
<!-- END OF TITLE -->
Note: Use end tag if lines are more than 5
NAMING RULES:
The naming rules are largely the same and to make things easier there are three important things to note in naming:
- Type to distinguish each type.
- Data type as a parameter to know the data type of the content after it is declared, besides this it will minimize the occurrence of errors.
- Naming that is easy to recognize and understand (don’t use abbreviations that only you and your god know like
x = 5.
First is class, second is function and third is variable.
CLASS
FORMAT: c[Class Type]_[Class Name].[File Extension]
EXAMPLE: cg_Mamal.java (Global/Public Class of Mamals), cs_Car.java (Static/Private Class of Cars)
TYPE OF CLASS:
- g = Global/Public
- s = Static/Private
- d = Data Class
- etc depending on the type programming language
FUNCTION
FORMAT: f[Function Type]_[Return Data Type]_[Function Name].[File Extension]
EXAMPLE : fg_tf_checkSquare.c (Global Function with return data type of boolean), fs_mainRun (Static Void Function)
TYPE OF FUNCTION:
- g = Global/Public
- s = Static/Private
- etc depending on the type programming language
VARIABLE
FORMAT: [Type of Variable]_[Data Type of Variable]_[Variable Name]
EXAMPLE : g_tf_status (Global Variable with Data Type of Boolean), s_str_name (Static Variable with Data Type of String), c_list_food (Constant Variable with Data Type of List)
TYPE OF VARIABLE:
- g = Global
- s = Static
- l = Local
- c = Constant
- etc depending on the type programming language
There is something else that is important for you to know when creating a name:
- Use these naming rules as a general reference and as necessary, adjust the naming rules to the programming language you are using, because each programming language also has different naming rules.
- Don’t write the same name as the keyword (if, else, for, while, etc), because it will create errors and cannot be read by a program.
- Avoid using initials such as using just one letter when naming a variable/function/class if the program is complex, because it will be confusing and difficult to distinguish.
- Do not prefix variable/function/class names with numbers, as this will make the compiler read them as values instead of variables/function/class. Therefore, if our variable/function/class requires a number in it, then the number should not be placed at the beginning.
- Avoid naming variables/function/class with common terms such as data. Naming it data doesn’t explain anything. The name will make you confused later. Instead, use a name that describes the value of the variable/function/class itself.
- Variables in Programming Language like JavaScript and etc. can only start with a letter or underscore. You cannot create a variable with a number prefix or use a symbol other than the underscore.
- Variable/function/class names cannot contain spaces. If the variable/function/class name has more than two words, then use camelCase format like this: firstName, lastName, catName.
- Name of variable/function/class must not contain special characters (!, /+*= and others).
Here are some rules for creating a function/class:
- Avoid creating many parameters in a function if they are not necessary. Because if there are too many arguments, it will be difficult to test or use. If there are more than three function arguments needed then it can be consolidated with your team. Instead of creating many function parameters, utilize objects as parameters.
- Make a function to do only one thing because if the function we create does many things, then the function will be difficult to compile and test. Functions that do many things also have no clear purpose. When creating a function that does more than one thing, try to break it down. Until each function actually does one thing. Of course, this also makes the code in the function much cleaner and easier to read.
- The function name must represent its purpose. we also need to pay attention to the naming of the function. Make sure the name given represents the purpose or task of the function. This can also help other developers easily find out the purpose of the function you created.
- Create functions to avoid code duplication. If you feel that you often write repetitive code. You should pay attention to the code. Because repetitive code is a strong candidate for creating a function. The goal is none other than so that the code can be reused, just by calling a function.
CONTROL STRUCTURE & PROGRAM BLOCK
Creating a program block structure that is easy to read is also very important. Apart from making it easier to understand code readability, this can also improve the neatness of code writing. Apart from that, it also makes it easier to carry out line by line testing or makes it easier to check the code by quality assurance.
EXAMPLE:
tf fg_tf_check_nume_inh( void )
{
tf ttf_chk_numeinh;
ttf_chk_numeinh = (tf)FALSE;
if ( ( stf_chk_iup_numeInh != (tf)TRUE ) /* within fix time APF/usft */
|| ( stf_chk_iup_inh_GE != (tf)TRUE ) ) /* within Time_inh_GE */
{
ttf_chk_numeinh = (tf)TRUE; /* time is not passed */
}
return( ttf_chk_numeinh );
}
COMPLEX EXAMPLE:
static tf fs_tf_check_ChangeOfMind( void )
{
struct st_commonStatus *sp;
u2 tu2_transType;
u2 tu2_newGearSt;
u2 tu2_outRpm;
u2 tu2_EGrpmSt_offset;
u2 tu2_EGrpmST;
u2 tu2_GearIdx;
tf ttf_chk_com;
tf ttf_chk_EGsts_START;
u1 tu1_ESS_ENG_ST_status_sq;
/* sp_SOLアクセス */
sp = &sp_SOL;
tu2_transType = sp->transType;
tu2_newGearSt = (u2)( sp->newGearState & GEAR_ST_MASK );
/* 初期化 */
ttf_chk_com = (tf)FALSE;
/* Change of mind 条件判定 */
/* ①and②and③ */
if ( ( gtf_idleStopFlag_sq == (tf)FALSE ) /* ① idlestopflag=0 */
&& ( tu2_transType >= (u2)GP_HREL_START ) /* 係合要素解放制御中 */
&& ( tu2_transType <= (u2)GP_HREL_END ) )
{
tu2_outRpm = gu2_outRpm_sq;
if ( ( tu2_newGearSt >= (u2)GEAR_ST_HEVREL_START )
&& ( tu2_newGearSt <= (u2)GEAR_ST_HEVREL_END ) )
{
tu2_GearIdx = (u2)MAP_GEAR_REV( gu2_newGear );
}
else if ( tu2_newGearSt == (u2)GEAR_ST_REV_HEVREL )
{
/* Rレンジ状態で、C3係合はgu2_bestGearと関係なくで、直接にGEAR_REVを使う */
/* Rレンジ係合要素解放制御はSUB側がないので、B2のデータを使う */
tu2_GearIdx = (u2)MAP_GEAR_REV( GEAR_REV );
}
else
{
/* ありえないが領域外参照防止のためガード */
tu2_GearIdx = (u2)0;
}
tu2_EGrpmSt_offset = tb_u2_Interpolate_u2( tu2_outRpm,
(u2*)&cu2_OutrpmSyncTable[0],
(u2*)&cu2_EGRPM_Start_offset[ tu2_GearIdx ][0],
NO_OUTRPM_HEV_AREA5 );
tu2_EGrpmST = ( cu2_EGrpm_start_engage + tu2_EGrpmSt_offset );
tu1_ESS_ENG_ST_status_sq = gu1_ESS_ENG_ST_status_sq;
ttf_chk_EGsts_START = fg_tf_chk_sqImp_EGsts_START();
if ( ( ( gu2_EGrpm_sq >= tu2_EGrpmST ) /* ② Egrpm≧EGRPM_Start_Engage+ EGRPM_Start_offset */
&& ( ttf_chk_EGsts_START == (tf)TRUE ) /* ③ EGstatus = EG_START */
&& ( sp_SOL.procState >= (u2)S10 ) ) /* ④ Hybird係合要素解放制御開始時ソレノイドパターン成立 */
&& ( ( stf_Hev_COM_RatioDiff == (tf)FALSE ) /* ⑤ abs(inRpm - outRpm×newgear)≧CulcthEngageRpm_HEV */
|| ( stf_Hev_COM_MainPrs == (tf)FALSE ) /* ⑥ Ps2が閾値以下 or メイン係合非作動 */
|| ( stf_Hev_COM_SubPrs == (tf)FALSE ) ) /* ⑦ PS1 < max(P_ApplyAllow_HEVREL , Ps_WAIT_HEVREL_S1) */
&& ( gtf_FlgNeAccAppAllow == (tf)TRUE ) /* ⑧ FlgNeAccAppAllow = TRUE */
&& ( ( ( gu1_ESS_ENG_ST_sq != (u1)4 ) /* ESS_ENG_ST ≠4 */
&& ( tu1_ESS_ENG_ST_status_sq == u1_SG_NORMAL ) ) /* gu1_ESS_ENG_ST_status = NORMAL */
|| ( tu1_ESS_ENG_ST_status_sq != u1_SG_NORMAL ) ) ) /* gu1_ESS_ENG_ST_status ≠ NORMAL */
{
ttf_chk_com = (tf)TRUE;
}
}
return ( ttf_chk_com );
}
CODING/TYPING/WRITING CODE RULES:
Make sure every format, space and indent in every typed program. follow the rules that have been determined as a reference to make it easier to read the code. Use the same structure for classes, functions, if, for, while, etc. (declaration and then opening curly brace { below it and don’t forget to close the curly brace } after you finish typing the declaration)
/******************************************************************************/
/* Function: */
/* fs_tf_mp3IsOn */
/* Outline: */
/* Check Status of MP3 */
/* Parameter: */
/* l_int_battery, l_tf_status */
/* Return Value: */
/* l_tf_isON */
/* Function Explanation: */
/* Check status condition of MP3 */
/* Note: */
/* Have a 3 conditions (ON, LOW_BATTERY & OFF) */
/* Traceability Reference ID: */
/* - */
/******************************************************************************/
static tf fs_tf_mp3IsOn(int l_int_battery, tf l_tf_status)
{
tf l_tf_isON; // Variable Declaration
/* If Statement when ON Condition */
if ( ( ( l_int_battery > 0 )
&& ( l_int_battery > 20 ) )
&& ( l_tf_status == ON ) )
{
l_tf_isON = ON; // Block Program when ON Condition
}
/* If Statement when LOW_BATTERY Condition */
else if ( ( ( l_int_battery >= 0 )
&& ( l_int_battery <= 20 ) )
&& ( l_tf_status == ON ) )
{
l_tf_isON = LOW_BATTERY; // Block Program when LOW_BATTERY Condition
}
/* Statement when OFF Condition */
else
{
l_tf_isON = OFF; // Block Program when OFF Condition
}
return(l_tf_isON) // Return Value of Status MP3
}
Note: Not all programming languages use curly braces {}, there are programming languages that only need a colon : to declare something and the declaration and completion of the statement is affected by indentation such as in the python programming language.
FOOTER RULES
Make sure that at the end of the file line use the comments below as a delimiter header indicating the end of the file:
Markup Languages:
<!---------------------------------------------------------------------------------------------->
<!-- END OF FILE -->
<!---------------------------------------------------------------------------------------------->
Programming Languages:
/******** END OF FILE *********************************************************/
IMPORTANT NOTE: Make sure to always provide a description with comments to clarify each program flow.
Are you using a mobile phone? If yes, please check the mobile version here to ensure it doesn’t look messy.