Clean Code Meaningful names Masaki Hayashi 2016 API for Game Development Clean Code Meaningful names Masaki Hayashi

5 Lectures from me Meaningful names Functions Workshop Comments Formatting + workshop (assignment) Mostly from a book "Clean Code"

Masaki HAYASHI（林正樹）, PhD. Self introduction Masaki HAYASHI（林正樹）, PhD. Associate Professor Department of Game Design, Uppsala University 1986 - 2006 NHK Science and Technology Research Laboratories (20 years) 2006 - 2011 Game and IT companies 2012 - Uppsala University Astrodesign, Inc. Engineering Researcher on Content

Clean code is pretty important in a long term. The book is based on Java, here we use Unity with C# The book is strongly related to OO programming Code should be easy to understand for other people For group work, and even for yourself Important in industry (if wanting to be a professional) An episode (about a genius programmer) The lectures introduce just cases. Try and think about it yourself (most important) Clean code is pretty important in a long term.

Meaningful names

Names... Names, names, names... Variables Functions Arguments Classes Projects Source files Directories Executions etc etc.....

The bad example... // リヴォルヴのアルゴリズム ========================= // リヴォルヴのアルゴリズム ========================= void Camera::initRevolve(float sx, float sy, float sz, float tx, float ty, float tz) { rsx = sx; rsz = sz; rt0 = - atan2((tx-sx), (sz-tz)); dist = sqrt((sx-tx)*(sx-tx) + (sy-ty)*(sy-ty) + (sz-tz)*(sz-tz)); rthe = 0.0f; rdest = destry * 3.14159265f / 180.0f; rry = camdata.ry; if(destry > 0.0f) rdifthe = destspeed * 0.03f; // 目分量で決めたスピード=0.03 else rdifthe = - destspeed * 0.03f; status = 1; }

Use intention-revealing names Good name is very important, seriously. Change them when you find better ones. eg. float d; // distance in meters "d" doesn't reveal anything. It needs what is measured and the unit. float distanceInMeters; float distanceInCentiMeters; float metersFromOrigin; float miliMetersFromGround;

Avoid disinformation Avoid false clues that would obscure the meaning of code. Don't use letters which means something in the platform. eg. int characterList; // serial number of group of characters "List" means "std::list" to programmers. Don't use it unless it's actually a " std::list" int serialNumberOfCharacterGroup; int characterGroup; .....

Avoid disinformation (cont.) Don't use "l" and "O" as variable names. ( lower case of "L" upper case of "o" ) int l = 1; if ( p == 0 ) a = O1; else l = 01; int l = 1; if ( p == 0 ) a = O1; else l = 01; ( Font: Verdana ) ( Font: SimSun ) It's annoying, really...

Make meaningful distinctions Don't make a name in an instant way in order to distinguish one to another. eg. int Camera::closeup() { int status, status1; ................... } Number-series naming should be avoided. int statusOfCameraPosition, statusOfCameraRotation;

Make meaningful distinctions (cont.) Noise words added to naming. eg. a1, a2, a3,... Camera, CameraData, CameraInfo,... klass, thiss, ... Classic example: void copyValue(int a1, int a2) { a1 = a2; } void copyValue(int destination, int source) { destination = source; }

Use pronounceable names If you can't pronounce it, you can't discuss it. Abbreviation is sometimes annoying, too. eg. int qt1ksu; int adjdstcam; int kokusaitenjijou; int numberOfQuestion; int adjustedDistanceOfCamera; int businessExpo;

Use searchable names Single-letter names and numeric constants have a trouble when to be searched. eg. "e" in a wide scope (eg. global variable) is impossible to locate by search function. If it's a local variable in a small method, it would be OK. eg. for(int e=0 ; e < maxNumberOfCamera ; e++) {...} for (int e=0 ; e < 5 ; e++) {...} const int WORK_DAYS_PER_WEEK = 5; for (int e=0 ; e < WORK_DAYS_PER_WEEK ; e++) {...}

Avoid encoding No more Hungarian notation. eg. int m_MyDevice; // member of a structure/class LPCTSTR lpszSourceName; // long pointer to a null-terminated string Reasons of no need Richer type system Compiler evolved Better IDEs (Integrated Development Environment) Trend of shorter classes and functions Just a clutter and a mark of old type code....

Avoid encoding Hungarian notation e.g. Win32 API HWND CreateWindow( LPCTSTR lpClassName , LPCTSTR lpWindowName, DWORD dwStyle , int x , int y , int nWidth , int nHeight , HWND hWndParent , HMENU hMenu , HANDLE hInstance , LPVOID lpParam ); Microsoft's Design Guidelines discourage developers from using Hungarian notation in .NET. https://msdn.microsoft.com/en-us/library/ms229045(v=vs.110).aspx

Excerpt from the Microsoft's Framework Design Guidelines Avoid encoding Excerpt from the Microsoft's Framework Design Guidelines Word Choice ✓ DO choose easily readable identifier names. For example, a property named HorizontalAlignment is more English-readable than AlignmentHorizontal. ✓ DO favor readability over brevity. The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis). X DO NOT use underscores, hyphens, or any other nonalphanumeric characters. X DO NOT use Hungarian notation. X AVOID using identifiers that conflict with keywords of widely used programming languages.

Avoid mental mapping Smart people is not a professional, sometimes. eg. Smart people sometimes want to show off their smartness via the code. however Professionals know "Clarity is king". Also, don't be humorous.... Kissaway ( = delete ) addsonofabitchheadershit() ( = AddHeader() )

Class names / method names Class names should be noun or noun phrase Method names should be verb or verb phrase eg. Class / objects: Camera, Account,... Method: getActiveCamera, setId, movePosition,...

Pick one word per concept Don't use multiple names for just one abstract concept eg. fetch, retrieve, get controller, manager, driver If those are the same functioning, unify it.

Final words... Try doing this for your code and see what happens. Don't fear other developers. It will pay off in a long term.