From bb22bc506676fd268ded3b3d6c7b7acea5dc2db9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Sun, 17 Jul 2022 17:49:43 +0200
Subject: Update type names and variable prefixes.
---
README | 62 +++++++++++++++++++++++++++++++++++++++++++++-----------------
1 file changed, 45 insertions(+), 17 deletions(-)
(limited to 'README')
diff --git a/README b/README
index 8aeed8d..77e46d6 100644
--- a/README
+++ b/README
@@ -56,20 +56,48 @@ the project.
Hacking
~~~~~~~
-Like many Windows programs, Episode Browser uses Hungarian notation.
-Following is a list of prefixes commonly used in the code base:
-
- lp = pointer ("long/far pointer")
- b = boolean (BOOL, int)
- i = integer
- siz = size (size_t)
- h = handle
- l = long
- w = "word" (WPARAM)
- dw = "double word" (DWORD)
- sz = zero-terminated string (char *)
- wsz = ... wide string (wchar_t *)
- tsz = ... tstring (TCHAR *)
- sm = ... managed string (std::string)
- wsm = ... (std::wstring)
- tsm = ... (std::basic_string<TCHAR>)
+Following is a summary of some coding conventions used in the project.
+
+ ... HUNGARIAN NOTATION ...
+
+ - p = pointer
+ - b = bool, BOOL, int (boolean value)
+ - i = integer
+ - h = handle
+ - hX = X handle (e.g., hWnd = HWND)
+ - l = long, LPARAM
+ - w = WORD, WPARAM
+ - dw = DWORD
+ - lvi = LVITEM
+ - sz = unmangaged, zero-terminated string (char *)
+ - wsz = ... wide string (wchar_t *)
+ - tsz = ... tstring (TCHAR *)
+ - str = ... managed string (std::string)
+ - wstr = ... (std::wstring)
+ - tstr = ... (std::basic_string<TCHAR>)
+
+ ... TYPES ...
+
+Here are some general guidelines for choosing what types to use:
+
+1) Don't use Windows-specific types that "hide" pointers.
+2) Where there is a Windows-specific type with the same name and
+ function as a standard type (e.g., CHAR = char), prefer the
+ standard type.
+3) Otherwise, prefer the Windows-specific type when interacting with
+ the Windows API.
+
+For example, prefer...
+
+ - char* over LPSTR
+ - char const* over LPCSTR
+ - LVITEM* over LPLVITEM
+ - int over INT
+ - DWORD over unsigned long
+ (when interacting with the Windows API)
+
+Note...
+
+ - that the second rule above does not apply to BOOL, which should not
+ be replaced with bool, as BOOL is an integer that may have other
+ values than 1 and 0.
--
cgit v1.2.3