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