Develop a consistent programming style for the project.

[programnoir]

So, I think it might be obvious to anyone reading the code that I have been coding by myself and have not been the most consistent about code structure. I'm taking suggestions on how to properly format the involved code.

[programnoir]

I will establish a current common style:

Document Hierarchy Overview

Classes and IDs are to be renamed using hyphen-case, to distinguish them from code entities. These class names should feel similar to the variable names in the JavaScript itself, and their names should reflect their tag name, location, and purpose. The general hierarchy goes like this:

• Document/Body
  • Marker (Should be renamed; purpose is to help with display settings)
  • Buttons that control dialog boxes and modal shadow.
  • Search bar
  • The header bar
  • Modal shadow
  • Nav container for AWESOME Menu
  • Nav button holder and button itself
  • First-level list items
    • Study Field button
    • Unordered list of topics
    • Topic list item
  • Accessibility Controls
  • Inputs controlling them.
  • Code Generation Dialog
  • And its controls.
  • Main Section
  • Main Content
    • Topic
    • Chapter
      • Section (Collection of links)
      • Resource
        • Summary
        • Details
  • "Home Page"
  • Loading Bar

[programnoir]

Renaming Process

I'm going to go in order of the files as they are linearly called.

1. index.php
2. style.css
3. section-toggle.js
4. db-init.js
5. db-populate.js
6. awesome-menu.js
7. gencode.js
8. search.js

The next post will list all the names, first, then do replacements.

[programnoir]

I'll begin with index.php and with class/ID names, which are given descriptive hyphen-case names.

Line No.	Type	Original Name(s)	Replacement Name(s)
1	Class	default, larger, largest	setting-font-default, setting-font-larger, setting-font-largest
19	Class	dark, bright	setting-theme-dark, setting-theme-bright
20	ID	marker	setting-unfolding-marker
20	Class	unfolded	setting-content-unfolded
21	ID	nav-button	wrapper-button-menu-closed
22	ID	button-nav-main	button-main-menu
23	Class	menu-icon	icon-main-menu
34	ID	search	line-input-search
36	ID	global-title	text-site-title
39	ID	draw-dark	background-black-alpha
41	ID	nav-main	wrapper-main-menu
42	ID	nav-button-open	wrapper-button-menu-open
45	ID	button-settings-accessibility	(keep)
48	Class	icon-external-link	(keep)
50	Class	submenu-li	wrapper-submenu-parent
51	ID	button-ul-programming	button-submenu-programming (etc)
51	Class	button-submenu and red	button-toggle-submenu and red
52	ID	ul-programming	submenu-programming

Things mainly repeat in a similar scheme for the menu until line 154

Line No.	Type	Original Name(s)	Replacement Name(s)
156	ID	access-controls	wrapper-settings-accessibility
157	ID	ac-title	text-accessibility-settings-title
158	ID	ac-desc	text-accessibility-settings-description
164	ID	theme-choice	setting-theme
171	ID	font-size	setting-font-size
178	ID	show-content	setting-content-unfold
181	ID	save-exit	wrapper-accessibility-save-exit
182	ID	buttonAccessSave	button-settings-accessibility-save
183	ID	buttonAccessExit	button-settings-accessibility-close
187	ID	gen-code	wrapper-code-generator
188	ID	gen-title	text-code-generator-title
188	Class	gen-group	group-focusable-code-generator
189	ID	gen-desc	text-code-generator-description
190	Class	col-left	wrapper-layout-half-left
194	ID	section	parameter-select-section
194	Class	select and gen-group	form-select-code-generator
198	ID	tagSelect	parameter-select-tag
221	ID	url	parameter-resource-url
221	Class	in and gen-group	form-line-input-code-generator
225	ID	summary	parameter-resource-summary
225	Class	in and gen-group	(defined above)
229	ID	details	parameter-resource-details
229	Class	in and gen-group	(defined above)
236	ID	out	text-output-code-generator
236	Class	gen-group	(defined above)
239	ID	copy	button-code-generator-copy-output
239	Class	gen-group	(defined above)
240	ID	close-gen-code	button-code-generator-close
240	Class	gen-group	(defined above)
245	ID	main-wrapper	wrapper-main-site-content
246	ID	main-content	wrapper-resource-content
247	ID	welcome	wrapper-home-page-content
251	ID	recommended	text-recommended-topics
268	ID	loading-bar	dynamic-loading-bar
268	class	done	loading-complete
269	ID	button-generate-code	button-code-generator

Dynamic classes

Original Name(s)	Replacement Name(s)
topic	(keep)
show (topic)	(deprecated)
hidden (topic)	(deprecated)
xc	chapter
bc	button-chapter-name
lc	resource
desc	resource-details
hidden (#"wrapper-home-page-content)	state-hidden
config (#background-black-alpha)	state-accessibility-settings
gen (#background-black-alpha)	state-code-generator
open (multiple nodes)	state-open

[programnoir]

HTML Node Element Attribute Order

1. ID/Name
2. Class/Property
3. All remaining attributes are in alphabetical order (make exceptions where common sense applies).

HTML Style Guide

Basics

• There is no tabbing; only single-space lines.

  Tags

• There are no spaces between the angle brackets < > and the first and last characters in them.
• Closing slashes (looks like this: />) are used whenever appropriate.
• In tags containing text and preceding nested tags, the text is given its own line.

  Tag Attributes

• There are no spaces between the attribute name, the operator, or the value.
• Double quotes are always used for attribute values.
• In similar-looking lines, do not space attributes to make columns.

[programnoir]

Okay, now for style.css

Basics

• No tabs; we use Allman style with single-spaces for tabbing.
• Layers are specified and explained at the top of the file.
• "Global" things like fonts and the universal selector go at the top.

CSS Rules

• Rules are divided into several groups in the same document.
  1. Global selectors and plain tag elements go at the top.
  2. Mobile sized screen, without any unique changes applied.
  3. Dynamically applied changes that do not relate to themes or sizes.
  4. Default and Dynamically-applied theme-related changes.
  5. Larger screens using @media rules for sizes only.
• Rules generally proceed from the most parental in the hierarchy to the child.
• These groups should be divided using comments.

Selectors

• Each selector longer than three characters gets its own line.
• Selectors that are three characters or shorter are grouped together at the end.
• Otherwise, selectors should try to be in hierarchy order, from parent to child.
• Parentheses and brackets spacing uses a single space for the beginning and end of its contents.

  html.example:not( .contents ),
  header[ role="banner" ]

Properties and Values

• Braces are used Allman style. Brackets and parentheses follow the aforementioned style guidelines.
• A property, then a colon, then a space, then the value, and a semicolon is applied: property: value;
• When selecting with attributes, no spaces are used around the = operator.
• The order in which properties are organized follow this format:
  1. Contents
  2. Display mode (block, table-cell, etc)
  3. Positioning (float:left, position:fixed, top:0, etc)
  4. External-positioning (margins)
  5. Border sizes (colors may be specified here to reduce file size)
  6. Padding amounts
  7. Dimensions (height and width, min-width, etc)
  8. Content positioning (text-align, vertical-align [table-cell only!], etc)
  9. Non-Cosmetic Content spacing (line-height, white-space, overflow etc)
  10. Cosmetic changes (box-shadow, background colors, font sizes, letter-spacing, font colors, etc).
  11. Post-processing (transform, transition)
  12. Animation
  13. Z-index values

[programnoir]

The remaining files are all JavaScript. So their style guides should go here.

Variable Names

Variables are descriptively named using camelCase. Because JavaScript is dynamically typed, I'll preface the variable name with a letter indicating the data type. The exception to this rule would be a variable intended for iteration.

Letter	Data/Information type
a	Array
b	Boolean
d	TaffyDB Database
f	Function
h	HTML/DOM object
i	Interval
k	Keys checked for input.
n	Numeric
o	Object (generic)
s	String
t	TaffyDB entry

Function Descriptions

Functions will get a multi-line comment describing their intended purpose above its declaration.

[programnoir]

Variable Name Replacements

File	Name	Replacement
section-toggle.js	keyConfirm	kConfirm
...	group_class_chapter	aByClassChapter
...	setText	fSetNewARIALabel
...	elem	hRelabeledElement
...	lc	hElement
...	txt	sNewARIALabel
...	toggleLC	fToggleFoldingTopicChapterResource
...	node_current	sNodeTagName
...	handleKeyUpLC	fHandleKeyUpResource
...	handleClickLC	fHandleClickResource
...	isTriggerchapter	fWrapperToggleChapter
...	me	hTargetChapter
...	group_sliced_chapters	aSlicedChapters
...	handleClickchapter	fHandleClickChapter
...	handleKeyUpChapter	fHandleKeyUpChapter
...	handleClickBC	fHandleClickChapterButton

File	Name	Replacement
db-init.js	db	dLinks
...	db_topics	dTopics
...	topic_id	sTopicID
...	topic	sTopic
...	topic_array	aChapters
...	section	sSection
...	tagName	sTag
...	tagColor	sTagColor
...	url	sURL
...	summary	sSummary
...	details	sDetails

[programnoir]

File	Name	Replacement
db-populate.js	refs	dResourceStack
...	total_tasks	nTotalTasks
...	bar_width	nBarWidthPercentage
...	current	nCurrentTask
...	interrupt_flag	bInterrupt
...	removeElement	fRemoveElement
...	node	hElement
...	range	hRange
...	pN	hParentElement
...	clearRefs	fClearDResourceStack
...	addNewModule	fAddNewResource
...	d	hDiv
...	tg	hTag
...	aa	hLink
...	dp	hDetails
...	first_result	oResource
...	addNewchapter	fCreateNewChapter
...	buttonText	sChapterName
...	import_id	sChapterID
...	chapter	hDiv
...	b	hButton
...	s	hSection
...	addNewchapterFromMenuClick	fAddChapterFromMenu
...	import_d	hTopic
...	import_i	nChapterArrayIndex
...	import_terms	aChapters
...	idT	sChapterID
...	bText	sChapterName
...	chapterNode	hChapter
...	addNewTopic	fCreateAndAddNewTopic
...	node_id	sTopicID
...	node_text	sTopicName
...	d	hDiv
...	dh2	hH2
...	increaseLoadingBar	fUpdateLoadingBar
...	loading_bar	hLoadingBar
...	doHeavyTask	fStartAsyncTask
...	params	oParameters
...	totalMillisAllotted	nMillisecondsAllotted
...	totalTasks	nTasksAllotted
...	tasksPerTick	nTasksPerTick
...	tasksCompleted	nCompletedTasks
...	totalTicks	nTotalTicks
...	interval	iCurrentAsyncTask
...	loading_bar	hLoadingBar
...	doTick	fTickTask
...	totalByEndOfTick	nCompletedTasksByTickEnd
...	task	fTask
...	taskUponCompletion	fUponAsyncTaskCompletion
...	removeTopicNodes	fRemoveTopicNodes
...	openedElements	aTopics
...	i_r	nTopicsIndex
...	removeResourceNodes	fRemoveResourceNodes
...	openedElements	aResources
...	i_r	nResourcesIndex
...	addModuleToRef	fCopyRecordToStack
...	i_record	aRecord
...	populateRefsWithResourcesBySection	fPopulateStackBySection
...	terms	aSectionNames
...	i	nSectionArrayIndex
...	populateRefsWithResourcesBySearch	fPopulateStackBySearch
...	s	sSearch
...	addAllEventListeners	fAddAllEventListeners
...	group_class_chapter	aByClassChapter
...	j	nChapterIndex
...	group_class_bc	aByClassChapterButtonName
...	j	nButtonIndex
...	getListOfSections	fGetChapterArray
...	node_selected	sQueriedTopicID
...	populateResourcesIntoTopic	fPopulateTopicWithStack
...	node_selected	sQueriedTopicID
...	terms	aChaptersFromQuery
...	populateTopicsBySection	fPopulateTopicsViaSection
...	node_selected	sQueriedTopicID
...	i	nChaptersQueryIndex
...	h2Text	sTopicName
...	d	hTopic
...	prepareTopicBySearch	fPrepareTopicViaSearch
...	populateTopicsBySearch	fPopulateTopicsViaSearch
...	k	nSectionIndex
...	i_tIndex	nTopicsIndex
...	i_a_sections	aSections
...	i_a_topics	aTopics
...	_k	nSectionIndexValue
...	text_button	sChapterName
...	sec	sCurrentSection
...	topic_selected	oSelectedTopic
...	z	nChaptersIndex
...	flagMadeTopicAlready	bAlreadyMadeTopic
...	l	nAlreadyTopicsIndex
...	_t	nTopicsIndexValue
...	eraseEventListeners	fEraseEventListeners
...	group_class_topic	aByClassTopic
...	j	nTopicIndex
...	populateByMenuClick	fPopulateViaMenu

[programnoir]

Now for awesome-menu.js

Old Name	Replacement Name
MS	oAwesomeMenu
App	fMenuApplication
isFirefox	bIsFirefox
lastFocused	hLastFocusedID
flagDialogAccess	bAccessibilityDialogOpen
keysMenu	kMenuShortcut
keysScroll	kScroll
keysMouse	kMouse
buttonNavMain	hMainMenuButton
navMain	hMainMenuWrapper
buttonsSubmenu	aByClassButtonToggleSubmenu
mainWrap	(not used; deprecated)
drawDark	hBlackBackground
buttonAccess	hAccessibilityDialogButton
dialogAccess	hAccessibilityDialog
set_cookie	fSetCookie
theme_value	sTheme
font_value	sFontSize
show_content_value	sUnfoldContent
lifespan_in_days	nLifespanDays
valid_domain	sValidDomain
domain_string	sDomain
get_cookie	fGetCookie
cookie_name	sCookieName
cookie_string	sCookie
cookie_array	aCookie
i	nCookieIndex
cookie_value	aCookieValue
setSiteSettings	fApplySettings
theme	sSettingTheme
fontsize	sSettingFontSize
showcontent	sSettingShowContent
focusDelay	fDelayFocusOnElement
me	hElement
preventDefault	(keep)
e	hEvent
preventDefaultForScrollKeys	fPreventScrollKeys
enableScroll	fEnableScroll
disableScroll	fDisableScroll
enableAccess	fTabScreenReaderOn
this_tag	hElement
disableAccess	fTabScreenReaderOff
enableSubmenuAccess	fSubmenuTabScreenOn
i	nSubmenuChildrenIndex
disableSubmenuAccess	fSubmenuTabScreenOff
enableAllAccess	fAllTabScreenOn
listChildren	aMainMenuChildren
i	nMenuChildrenIndex
childButton	hButton
sibUL	hSiblingList
disableAllAccess	fAllTabScreenOff
moveButtonIn	fMoveMenuButtonToOpen
moveButtonOut	fMoveMenuButtonToClosed
openhMainMenuWrapper	fOpenMainMenu
closehMainMenuWrapper	fCloseMainMenu
openedElements	aSlicedMenuOpenChildren
i	hMenuOpenChild
isDescendent	fIsDescendent
parent	hParent
child	hChild
node	hNode
isNavFocused	fIsNavFocused
retrieveText	fRetrieveText
elem	hElement
openSubmenu	fOpenSubmenu
submenu	hSubmenu
toFocus	hFirstSubmenuItem
closeSubmenu	fCloseSubmenu
closeAllSubmenus	fCloseAllSubmenus
submenuButtons	aSlicedSubmenuButtons
i	hSubmenuButton
toggleSubmenu	fToggleSubmenu
evtClickButtonSubmenu	fEventClickSubmenu
evtClickhMainMenuButton	fEventClickMainMenuButton
closehAccessibilityDialog	fCloseAccessibilityDialog
buttonshAccessibilityDialog	aByTagNameButton
selectshAccessibilityDialog	aByTagNameSelect
i	hButtonArrayIndex
i	hSelectArrayIndex
evtKeyUpGlobal	fEventKeyUpGlobal
ae	sActiveNodeName
evtBlurLastNav	fEventBlurLastMenuItem
lastNav	hLastMenuItem
evtBlurAccessExit	fEventBlurAccessibility
evtClickDarkDraw	fEventClickBlackBackground
evtClickhAccessibilityDialogButton	fEventClickAccessibilityDialogButton
evtClickButtonSave	fEventClickAccessibilitySaveButton
z	hUnfoldCheckbox
options	aOptions
evtKeyButton	fEventKeyDownOnButton
handleMenuClick	fHandleMenuClick
this_timer	iTimer
targ	hTopic
initApp	fInitApplication
submenuButtons	aSlicedSubmenuButtons
i	hSubmenuButton
navLast	hLastMenuItem
allElems	aByTagNameButton
j	nButtonIndex
menuItems	aMenuAnchors
i	nMenuAnchorIndex
i	nRecommendedIndex

[programnoir]

gen-code.js

Original Name	Replacement Name
App2	fCodeGeneratorApplication
dialogGenCode	hCodeGeneratorWrapper
populateSections	fPopulateSectionParameter (total rewrite)
secSel	hSelectSection
convertIO	fCreateCodeString (mostly a rewrite)
str	sCode
tag	aTagValues
updateOutput	fUpdateOutputText
exitGenCode	fCloseCodeGenerator
AllButtons	aByClassFocusableFields
i	nFocusableFieldsIndex
evtBlurCodeGenExit	fEventBlueCodeGenerator
assignEventListeners	fApplyEventListeners
inp	aByClassLineInput
i	nLineInputsIndex
i	nSelectsIndex
cB	hCopyButton

[programnoir]

search.js

Name	Replacement
input_search	hSearch
node_saved_section	sSavedChapter
string_search	sSearchQuery
timer	iSearchTimer
beginNewSearch	fNewSearch
array_of_sections	aDistinctQueriedChapters
array_of_topics	aQuerysTopics
topic_index	nQuerysTopicsIndex
k	nSectionIndexValue
o_kt	oSectionsTopicsIndices
revertState	fHandleSearchEmpty
handleSearchInput	fHandleSearchInput
value_input_search	sSearchValue

[programnoir]

No need for this now that #6 has been merged.