Doc Style Guide (#3462)

* First pass at style guide.

* Remove unused indenting tools.

* Update all C and H files to match style guide vim comment.

* Add vim formatting codes to poncho, taskvine, work_queue Python files.

* Update STYLE.md with standard library modules.

STYLE.md

@@ -0,0 +1,115 @@
+# Coding Style in CCTools
+
+The core of CCTools is written in C, while we also have a number of
+libraries and tools for end user access written in Python.  
+
+No style guide will exhaustively cover all situations, and there
+may be valid reasons to deviate from these suggestions.
+Nonetheless, strive to match the existing style of the code,
+for the benefit of readers that follow you
+
+## C Style Guidelines
+
+### C Module Design
+
+C source code should be broken into modules, each of which defines a
+set of related operations on a common structure that can be reused.
+Keep the names of files, structures, and functions ruthlessly consistent.
+
+For example, if you are defining a module for slicing cheese:
+- The interface should be described in `cheese_slicer.h`
+- The implementation should be given in `cheese_slicer.c`
+- The object should be a `struct cheese_slicer`
+- The functions operating on `cheese_slicer` should begin with the name `cheese_slicer` and accept a first argument of `struct cheese_slicer`
+- The structure should be created by functions like this:
+```
+struct cheese_slicer * cheese_slicer_create( ... );
+void                   cheese_slicer_delete( struct cheese_slicer *s );
+```
+- Functions and variables that are private to the module should be marked as `static`, not mentioned in the `.h` file, and may have names without the
+module prefix.
+
+### C Utility Modules
+
+Please familiarize yourself with the [many utility modules](https://cctools.readthedocs.io/en/stable/api/html/taskvine__json_8h.html)
+that serve as our extended "standard library".  Use them instead of rolling your own from scratch:
+
+- Data Structures:
+[set](https://cctools.readthedocs.io/en/stable/api/html/set_8h.html)
+[list](https://cctools.readthedocs.io/en/stable/api/html/list_8h.html)
+[hash_table]((https://cctools.readthedocs.io/en/stable/api/html/hash_table_8h.html)
+[itable](https://cctools.readthedocs.io/en/stable/api/html/itable_8h.html)
+- Network Access:
+[link (TCP)](https://cctools.readthedocs.io/en/stable/api/html/link_8h.html)
+[datagram (UDP)](https://cctools.readthedocs.io/en/stable/api/html/datagram_8h.html)
+[domain_name_cache (UDP)](https://cctools.readthedocs.io/en/stable/api/html/domain_name_cache_8h.html)
+- File Manipulation:
+[path](https://cctools.readthedocs.io/en/stable/api/html/path_8h.html)
+[full_io](https://cctools.readthedocs.io/en/stable/api/html/full_io_8h.html)
+[sort_dir](https://cctools.readthedocs.io/en/stable/api/html/sort_dir_8h.html)
+[mkdir_recursive](https://cctools.readthedocs.io/en/stable/api/html/mkdir_recursive_8h.html)
+[unlink_recursive](https://cctools.readthedocs.io/en/stable/api/html/unlink_recursive_8h.html)
+[trash](https://cctools.readthedocs.io/en/stable/api/html/trash_8h.html)
+- JX (JSON Extended) Manipulation:
+[jx](https://cctools.readthedocs.io/en/stable/api/html/jx_8h.html)
+[jx_parse](https://cctools.readthedocs.io/en/stable/api/html/jx_parse_8h.html)
+[jx_print](https://cctools.readthedocs.io/en/stable/api/html/jx_print_8h.html)
+[jx_eval](https://cctools.readthedocs.io/en/stable/api/html/jx_eval_8h.html)
+- String Handling: 
+[stringtools](https://cctools.readthedocs.io/en/stable/api/html/stringtools_8h.html)
+
+In particular, we make extensive use of `string_format` to construct and dispose of variable length strings like this:
+```
+char *mydatapath = string_format("%s/%d/data",mypath,day);
+...
+free(mydatapath);
+```
+
+### C Indenting
+
+Code should be indented like this using hard tabs:
+
+```
+int cheese_wheel_slice( struct cheese_wheel *c, int nslices )
+{
+	if( ... ) {
+		while( ... ) {
+			...
+		}
+	} else {
+		...
+	}
+}
+```
+
+### C Indenting Configuration
+
+If you use vim, the basic indenting setup is given by a comment at the bottom of each file:
+```
+/* vim: set noexpandtab tabstop=8: */
+```
+
+If you use emacs, put the following in `$HOME/.emacs.d/init.el` to achieve the same effect:
+
+```
+; Force indentation with a hard tab instead of spaces.
+(setq-default indent-tabs-mode t)
+
+; For display purposes, a tab is eight spaces wide
+(setq-default tab-width 8)
+
+; Each indentation level is one tab.
+(defvaralias 'c-basic-offset 'tab-width)
+```
+
+## Python Style Guidelines
+
+TBA
+
+### Python Indenting Configuration
+
+If you use vim, the basic indenting setup is given by a comment at the bottom of python source files:
+
+```
+# vim: set sts=4 sw=4 ts=4 expandtab ft=python:
+```

batch_job/src/batch_job.c

@@ -307,4 +307,4 @@ int batch_fs_unlink (struct batch_queue *q, const char *path)
 	return q->module->fs.unlink(q, path);
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_blue_waters.c

@@ -337,4 +337,4 @@ const struct batch_queue_module batch_queue_blue_waters = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_chirp.c

@@ -407,4 +407,4 @@ const struct batch_queue_module batch_queue_chirp = {
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_cluster.c

@@ -708,4 +708,4 @@ const struct batch_queue_module batch_queue_slurm = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_condor.c

@@ -412,4 +412,4 @@ const struct batch_queue_module batch_queue_condor = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_dryrun.c

@@ -243,4 +243,4 @@ const struct batch_queue_module batch_queue_dryrun = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_internal.h

@@ -75,4 +75,4 @@ struct batch_queue {
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_k8s.c

@@ -721,4 +721,4 @@ const struct batch_queue_module batch_queue_k8s = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_k8s_script.c

@@ -101,5 +101,5 @@ main()\n\
 }\n\
 \n\
 main\n\
-# vim: set noexpandtab tabstop=4:\n\
+# vim: set noexpandtab tabstop=8:\n\
 ";

batch_job/src/batch_job_local.c

@@ -165,4 +165,4 @@ const struct batch_queue_module batch_queue_local = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_mesos.c

@@ -419,4 +419,4 @@ const struct batch_queue_module batch_queue_mesos = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_mpi.c

@@ -732,4 +732,4 @@ void batch_job_mpi_setup( const char *debug_file_name, int manual_cores, int man
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_vine.c

@@ -300,4 +300,4 @@ const struct batch_queue_module batch_queue_vine = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_job_work_queue.c

@@ -300,4 +300,4 @@ const struct batch_queue_module batch_queue_wq = {
 	},
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_task.c

@@ -216,4 +216,4 @@ char * batch_task_generate_id(struct batch_task *t) {
 	return xxstrdup(t->hash);
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_task.h

@@ -121,4 +121,4 @@ void batch_task_set_info(struct batch_task *t, struct batch_job_info *info);
 char * batch_task_generate_id(struct batch_task *t);
 
 #endif
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_wrapper.c

@@ -340,4 +340,4 @@ char *batch_wrapper_expand(struct batch_task *t, struct jx *spec) {
 	return result;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/batch_wrapper.h

@@ -88,4 +88,4 @@ char *batch_wrapper_write(struct batch_wrapper *w, struct batch_task *t);
 char *batch_wrapper_expand(struct batch_task *t, struct jx *spec);
 
 #endif
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/mesos_task.c

@@ -40,4 +40,4 @@ void mesos_task_delete(struct mesos_task *mt)
 	free(mt);
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/mesos_task.h

@@ -22,4 +22,4 @@ void mesos_task_delete(struct mesos_task *mt);
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/vine_factory.c

@@ -1579,4 +1579,4 @@ int main(int argc, char *argv[])
 	return 0;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

batch_job/src/work_queue_factory.c

@@ -1637,4 +1637,4 @@ int main(int argc, char *argv[])
 	return 0;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_acl.c

@@ -987,4 +987,4 @@ int chirp_acl_init_reserve(const char *path, const char *subject)
 	}
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_acl.h

@@ -69,4 +69,4 @@ int chirp_acl_whoami(const char *subject, char **esubject);
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_alloc.c

@@ -527,4 +527,4 @@ INT64_T chirp_alloc_mkalloc(const char *path, INT64_T size, INT64_T mode)
 	return result;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_alloc.h

@@ -28,4 +28,4 @@ INT64_T chirp_alloc_fstatfs(int fd, struct chirp_statfs *buf);
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_audit.c

@@ -155,4 +155,4 @@ void chirp_audit_delete(struct hash_table *table)
 	hash_table_delete(table);
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_audit.h

@@ -25,4 +25,4 @@ void chirp_audit_delete(struct hash_table *table);
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_benchmark.c

@@ -258,4 +258,4 @@ int main(int argc, char *argv[])
 	return 0;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_client.c

@@ -2175,4 +2175,4 @@ INT64_T chirp_client_job_reap (struct chirp_client *c, const char *json, time_t
 	return get_result(c, stoptime);
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_client.h

@@ -139,4 +139,4 @@ INT64_T chirp_client_job_reap(struct chirp_client *c, const char *json, time_t s
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_distribute.c

@@ -831,4 +831,4 @@ int main(int argc, char *argv[])
 	return 0;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_filesystem.c

@@ -917,4 +917,4 @@ int cfs_stub_job_schedule(sqlite3 * db)
 	return ENOSYS;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_filesystem.h

@@ -164,4 +164,4 @@ extern char   chirp_url[CHIRP_PATH_MAX];
 
 #endif /* CHIRP_FILESYSTEM_H */
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_chirp.c

@@ -468,4 +468,4 @@ struct chirp_filesystem chirp_fs_chirp = {
 	cfs_stub_job_schedule,
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_chirp.h

@@ -13,4 +13,4 @@ extern struct chirp_filesystem chirp_fs_chirp;
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_confuga.c

@@ -706,4 +706,4 @@ struct chirp_filesystem chirp_fs_confuga = {
 	chirp_fs_confuga_job_schedule,
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_confuga.h

@@ -13,4 +13,4 @@ extern struct chirp_filesystem chirp_fs_confuga;
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_hdfs.c

@@ -770,4 +770,4 @@ struct chirp_filesystem chirp_fs_hdfs = {
 	cfs_stub_job_schedule,
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_hdfs.h

@@ -13,4 +13,4 @@ extern struct chirp_filesystem chirp_fs_hdfs;
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_local.c

@@ -1117,4 +1117,4 @@ struct chirp_filesystem chirp_fs_local = {
 	chirp_fs_local_job_schedule,
 };
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_local.h

@@ -15,4 +15,4 @@ int chirp_fs_local_resolve (const char *path, int *dirfd, char basename[CHIRP_PA
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fs_local_scheduler.c

@@ -1127,4 +1127,4 @@ int chirp_fs_local_job_schedule (sqlite3 *db)
 	return rc;
 }
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */

chirp/src/chirp_fuse.c

@@ -733,4 +733,4 @@ int main(int argc, char *argv[])
 
 #endif
 
-/* vim: set noexpandtab tabstop=4: */
+/* vim: set noexpandtab tabstop=8: */