WIP: Cadence Style Guide #3

alilloig · 2022-07-28T16:47:23Z

Closes #2

Description

Developers need better guidelines for how to write clean cadence code. Define those guidelines at docs/cadence-style-guide.md. Early PR containing only table of contents to seek consensus about which points should the guide contain and check everyone's thoughts on conflictive aspects.

Targeted PR against master branch
Linked to Github issue with discussion and accepted design OR link to spec that describes this work
Updated relevant documentation
Re-reviewed Files changed in the Github PR explorer
Added appropriate labels

joshuahannan

Looks good so far!

joshuahannan · 2022-07-28T17:21:46Z

cadence-style-guide.md

+                  .getCapability(ContractName.SomeAbsurdlyLongForSomeReasonPathName)
+                  .borrow<&SomeResource{ContractName.InterfaceName}>()
+```
+Keep allways those concatenated function calls idented from the object they are being called from.


Suggested change

Keep allways those concatenated function calls idented from the object they are being called from.

Always keep those concatenated function calls indented from the object they are being called from.

cadence-style-guide.md

joshuahannan · 2022-07-28T17:28:59Z

cadence-style-guide.md

+## Comments
+Comments are a vital part of smart contracts, allowing users to easily understand what they are getting involve with. 
+### High level documentation at the begining of files (contracts, transactions and scripts)
+Top Level comments and comments for types, fields, events, and functions should use `///` (three slashes) because there is a cadence docs generating tool that picks up three slash comments to auto-generate docs.


Can you link to the docgen section in the cadence repo here?

joshuahannan · 2022-07-28T17:30:01Z

cadence-style-guide.md

+Functions should be commented with a:
+  * Description
+  * Parameter descriptions (unless it is obvious)
+  * Return value descriptions (unless it is obvious)


This should be removed from here and created as an issue in this repo so we can discuss it

cadence-style-guide.md

Co-authored-by: Joshua Hannan <joshua.hannan@dapperlabs.com>

turbolent · 2022-09-01T23:42:18Z

cadence-style-guide.md

+Use 4 spaces per indentation level.
+Prefer spaces over tabs as indentation method, mixing them should be avoided.
+## Line length
+A line length of 80 characters is recommended for Cadence. This could be particularly challenging when writing capability-related lines, for instance:


I agree the guide should recommend a reasonable maximum line length, but we're not writing code on punch cards anymore. Maybe something like 100?

turbolent · 2022-09-01T23:42:49Z

cadence-style-guide.md

+1. [Naming and capitalization](#naming-and-capitalization)
+## Indentation
+Use 4 spaces per indentation level.
+Prefer spaces over tabs as indentation method, mixing them should be avoided.


Add line breaks between Markdown elements, to make it easier to read and edit:

Suggested change

1. [Naming and capitalization](#naming-and-capitalization)

## Indentation

Use 4 spaces per indentation level.

Prefer spaces over tabs as indentation method, mixing them should be avoided.

1. [Naming and capitalization](#naming-and-capitalization)

## Indentation

Use 4 spaces per indentation level.

Prefer spaces over tabs as indentation method, mixing them should be avoided.

turbolent · 2022-09-01T23:45:19Z

cadence-style-guide.md

+```cadence
+letResourceRef = account.getCapability(ContractName.SomePathName).borrow<&SomeResource{ContractName.InterfaceName}>()
+```
+This generic line of code that can be found in many transactions that need to borrow a reference to a certain object from a capability is 118 characters long by its own without any indentation. Keeping this line readable should be an objective of any Cadence developer. There are some simple patterns that could be observed in order to accomplish this:


Add line breaks after logical ends, i.e. put logical parts of the paragraph on separate lines:

Suggested change

This generic line of code that can be found in many transactions that need to borrow a reference to a certain object from a capability is 118 characters long by its own without any indentation. Keeping this line readable should be an objective of any Cadence developer. There are some simple patterns that could be observed in order to accomplish this:

The following line of code is an example of code that can be found in many transactions.

It borrows a reference to a certain object from a capability, and is 118 characters long without any indentation.

Keeping this line readable should be an objective of any Cadence developer.

There are some simple practices that should be followed in order to accomplish this:

turbolent · 2022-09-01T23:45:58Z

cadence-style-guide.md

+letResourceRef = account.getCapability(ContractName.SomePathName).borrow<&SomeResource{ContractName.InterfaceName}>()
+```
+This generic line of code that can be found in many transactions that need to borrow a reference to a certain object from a capability is 118 characters long by its own without any indentation. Keeping this line readable should be an objective of any Cadence developer. There are some simple patterns that could be observed in order to accomplish this:
+ Prefer to always break the line before the `borrow` call.


+ is uncommen in Markdown lists, prefer to use * or -

turbolent · 2022-09-01T23:46:33Z

cadence-style-guide.md

+This generic line of code that can be found in many transactions that need to borrow a reference to a certain object from a capability is 118 characters long by its own without any indentation. Keeping this line readable should be an objective of any Cadence developer. There are some simple patterns that could be observed in order to accomplish this:
+ Prefer to always break the line before the `borrow` call.
+```cadence
+letResourceRef = account.getCapability(ContractName.SomePathName)


Suggested change

letResourceRef = account.getCapability(ContractName.SomePathName)

let resourceRef = account.getCapability(ContractName.SomePathName)

turbolent · 2022-09-01T23:46:38Z

cadence-style-guide.md

+```
+ If indentation or a long path name makes the "getCapability" line go further than 80 characters an additional line break can be included
+```cadence
+letResourceRef = account


Suggested change

letResourceRef = account

let resourceRef = account

turbolent · 2022-09-01T23:48:18Z

cadence-style-guide.md

+## Comments
+Comments are a vital part of smart contracts, allowing users to easily understand what they are getting involved with. 
+### High level documentation at the begining of files (contracts, transactions and scripts)
+Top Level comments and comments for types, fields, events, and functions should use `///` (three slashes) because [the cadence docs generating tool](https://github.com/onflow/cadence/tree/master/tools/docgen) picks up three slash comments to auto-generate docs.


Suggested change

Top Level comments and comments for types, fields, events, and functions should use `///` (three slashes) because [the cadence docs generating tool](https://github.com/onflow/cadence/tree/master/tools/docgen) picks up three slash comments to auto-generate docs.

Top-level comments and comments for types, fields, events, and functions should use `///` (three slashes) because [the Cadence documentation generator](https://github.com/onflow/cadence/tree/master/tools/docgen) uses them to differentiate between normal comments and documentation comments.

turbolent · 2022-09-01T23:50:14Z

cadence-style-guide.md

+### Contracts
+Contract and contract interfaces names should always follow PascalCase, for instance:


Suggested change

### Contracts

Contract and contract interfaces names should always follow PascalCase, for instance:

### Types

Type names should always follow CamelCase and start with an uppercase letter, for instance:

turbolent · 2022-09-01T23:50:56Z

cadence-style-guide.md

+```cadence
+pub contract ExampleToken
+```
+### Fields


Suggested change

### Fields

### Fields

Field names should always follow camelCase, and start with a lowercase letter, for instance:

turbolent · 2022-09-01T23:51:14Z

cadence-style-guide.md

+```
+// Different rule for regular fields than for path fields?
+### Functions
+Function names should always follow camelCase, for instance:


Suggested change

Function names should always follow camelCase, for instance:

Function names should always follow camelCase, and start with a lowercase letter, for instance:

bluesign · 2022-09-05T19:25:03Z

cadence-style-guide.md

+pub var totalSupply
+```
+```cadence
+pub var VaultStoragePath


Suggested change

pub var VaultStoragePath

pub let VaultStoragePath

I think rule here is related to being constant, but I am not sure.

Add style guide draft

f755fab

alilloig added the SC-Eng Issues that we want to see surfaced in SC-Eng ZH Board label Jul 28, 2022

alilloig requested review from joshuahannan and satyamakgec July 28, 2022 16:47

alilloig linked an issue Jul 28, 2022 that may be closed by this pull request

Create Cadence Style Guide #2

Open

alilloig changed the title ~~Cadence Style Guide~~ WIP: Cadence Style Guide Jul 28, 2022

alilloig requested review from dsainati1, SupunS and turbolent July 28, 2022 16:48

joshuahannan reviewed Jul 28, 2022

View reviewed changes

alilloig and others added 2 commits July 28, 2022 19:47

Apply suggestions from code review

c1ba595

Co-authored-by: Joshua Hannan <joshua.hannan@dapperlabs.com>

Apply suggestions from review

4a19c14

turbolent reviewed Sep 1, 2022

View reviewed changes

bluesign reviewed Sep 5, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: Cadence Style Guide #3

WIP: Cadence Style Guide #3

alilloig commented Jul 28, 2022

joshuahannan left a comment

joshuahannan Jul 28, 2022

joshuahannan Jul 28, 2022

joshuahannan Jul 28, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

turbolent Sep 1, 2022

bluesign Sep 5, 2022

bluesign Sep 5, 2022 •

edited

Loading

	Keep allways those concatenated function calls idented from the object they are being called from.
	Always keep those concatenated function calls indented from the object they are being called from.

-This generic line of code that can be found in many transactions that need to borrow a reference to a certain object from a capability is 118 characters long by its own without any indentation. Keeping this line readable should be an objective of any Cadence developer. There are some simple patterns that could be observed in order to accomplish this:
+The following line of code is an example of code that can be found in many transactions.
+It borrows a reference to a certain object from a capability, and is 118 characters long without any indentation.
+Keeping this line readable should be an objective of any Cadence developer.
+There are some simple practices that should be followed in order to accomplish this:

	letResourceRef = account.getCapability(ContractName.SomePathName)
	let resourceRef = account.getCapability(ContractName.SomePathName)

	Top Level comments and comments for types, fields, events, and functions should use `///` (three slashes) because [the cadence docs generating tool](https://github.com/onflow/cadence/tree/master/tools/docgen) picks up three slash comments to auto-generate docs.
	Top-level comments and comments for types, fields, events, and functions should use `///` (three slashes) because [the Cadence documentation generator](https://github.com/onflow/cadence/tree/master/tools/docgen) uses them to differentiate between normal comments and documentation comments.

		### Contracts
		Contract and contract interfaces names should always follow PascalCase, for instance:

	Function names should always follow camelCase, for instance:
	Function names should always follow camelCase, and start with a lowercase letter, for instance:

WIP: Cadence Style Guide #3

Are you sure you want to change the base?

WIP: Cadence Style Guide #3

Conversation

alilloig commented Jul 28, 2022

Description

joshuahannan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bluesign Sep 5, 2022 • edited Loading

Choose a reason for hiding this comment

bluesign Sep 5, 2022 •

edited

Loading